On Fri, Dec 3, 2021 at 3:52 AM Yetoo Happy <yetooha...@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
