Re: Bug#1016832: release-notes: Chapter 4 Upgrading commands are spread out over 20 pages
Daniel Lewart <lewart3@gmail.com> writes:
> Package: release-notes
> Severity: wishlist
>
> Debian Documention Team,
just a user here, but since no-one replied i thought id give my view
> Chapter 4. "Upgrades from Debian 10 (buster)" has commands spread out
> over 20 pages. I think many (most?) admins would enjoy a quick checklist
> or summary.
I think you are onto something, but i think that a checklist might not
be the way to go (reasons below).
I do think the structure of release-notes could be clearer about which
things are 'generic good practice' and which are release-specific.
The first category of generic good practice includes things like running
script(1) and informing users of downtime: people that have done
upgrades several times can skip these, but it's not always obvious
which these are, or where the division lies - i'd suggest putting these
into one chapter for example. The second set are the things that
everyone wants to read - changes to security section, whether the kernel
needs to be upgraded first etc. (Perhaps there is a third set about new
packages)
But I'd suggest against a checklist for a couple of reasons
* Encourages duplication. All the content will need to be written twice
how do you decide what, if anything, to leave out of the checklist. And
if the two say slightly different things then how will a user know which
is correct?
* Cant be automatic - eg your example "edit sources.list"
* Discourages understanding - same example, if the checklist doesnt
explain that there was a change here then some people will probably
miss it and will request more text in the checklist.
Reply to: