Re: Make etcupdate bootstrap requirement due to previous mergemaster usage more clear in handbook

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 that at 24.5.6.1 Merging Configuration Files are instructions to bootstrap etcupdate 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 being 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 the documentation and all the user groups speak so highly of the handbook being complete and thorough and authoritative, are just going to 24.5.1. Quick Start and follow the instructions and get to step 7 and may think that even though etcupdate is different from mergemaster from the last time they used the handbook they have faith that following the instructions won't brick 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 Merging Configuration Files because the user doesn't know that step exists or relevant to the current step and ends up unknowingly having etcupdate append "<<<< yours ... >>>>> new" to the top of the user's very important configuration files that they didn't expect the program to actually modify that way when they resolved differences nor could they predict easily because the 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 what might have happened and scrolls down to find 24.5.6.1 Merging Configuration 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 Step 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. Quick 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 right 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. The next best option is a warning at the top because it reduces the chance of 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 frustration 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=260253