Date: Thu, 23 Dec 2021 19:08:45 -0800 From: Yetoo Happy <yetoohappy@gmail.com> To: freebsd-doc@freebsd.org Cc: freebsd-current@freebsd.org Subject: Re: Make etcupdate bootstrap requirement due to previous mergemaster usage more clear in handbook Message-ID: <CALT2f4s0c2SjAGfxEtphX6wrprR4%2BVJKR_bSyzZf_7LAB=QQgg@mail.gmail.com> In-Reply-To: <CALT2f4tzUw_-LZ7kwa8m=iRQFshNKDxM3DAcLjPw3eN8OZBthQ@mail.gmail.com> References: <CALT2f4tzUw_-LZ7kwa8m=iRQFshNKDxM3DAcLjPw3eN8OZBthQ@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Dec 3, 2021 at 3:52 AM Yetoo Happy <yetoohappy@gmail.com> wrote: > > In https://docs.freebsd.org/en/books/handbook/cutting-edge/ I can see tha= t at 24.5.6.1 Merging Configuration Files are instructions to bootstrap etc= update if switching from mergemaster. This is really convenient and really = useful, EXCEPT for that fact that it is placed in a part of the handbook a = little ways after installation would complete. The critical issue here bein= g that, due to this information not being higher up, a user who is looking = at the handbook to update from source and are trusting the handbook because= they have faith that it won't play any dirty tricks on them, because all t= he documentation and all the user groups speak so highly of the handbook be= ing complete and thorough and authoritative, are just going to 24.5.1. Quic= k Start and follow the instructions and get to step 7 and may think that ev= en though etcupdate is different from mergemaster from the last time they u= sed the handbook they have faith that following the instructions won't bric= k their system. This user will instead find that faith in general is just a= very complex facade for the pain and suffering of not following 24.5.6.1 M= erging Configuration Files because the user doesn't know that step exists o= r relevant to the current step and ends up unknowingly having etcupdate app= end "<<<< yours ... >>>>> new" to the top of the user's very important conf= iguration files that they didn't expect the program to actually modify that= way when they resolved differences nor could they predict easily because t= he diff format is so unintuitive and different from mergemaster. Now unable= to login or boot into single user mode because redirections instead of the= actual configuration is parsed the user goes to the handbook to find out w= hat might have happened and scrolls down to find 24.5.6.1 Merging Configura= tion Files is under 24.5.6. Completing the Update. What a mocking section? = Completing the update? How could I have completed the update if I was on St= ep 7 of Quick Steps? The user now may feel cheated, jaded, or insulted and = wonder what the fuss is all about with this hyped documentation. > > Here's a solution: Make a red warning notice at the very top of 24.5.1. Q= uick Start and refer to 24.5.6.1 Merging Configuration Files and make clear= this is for step 7. Another solution is, if possible, put that red warning= notice next to step 7 or step 7 in the grey section or red/pink section of= the quick start box area, I personally would prefer a warning with text ri= ght next to step 7 in the red/pink part of the quick start box, but I'm not= sure if that's possible or respecting the documentation design paradigm. T= he next best option is a warning at the top because it reduces the chance o= f a user following instructions and missing that step because they haven't = scrolled to that point yet. > > I'm sorry if this comes across as an angry potentially combative message,= but I just wanted to make clear where and what the problem is and my frust= ration with this problem. Around the time I made this post, I created a patch that I believe resolves the issue with the documentation. Here is the PR for posterity: https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=3D260253
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CALT2f4s0c2SjAGfxEtphX6wrprR4%2BVJKR_bSyzZf_7LAB=QQgg>