• Re: Bug#1016832: release-notes: Chapter 4 Upgrading commands are spread

    From RL@21:1/5 to Daniel Lewart on Sat Aug 13 13:10:01 2022
    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.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)