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

From: Yetoo Happy <>
Date: Fri, 03 Dec 2021 11:52:13 UTC
In I can see that
at* 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 * 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 * 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 * 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.