intrigeri:
> xin:
>> Hello, an anchor is missing in a link in the 4.0 release notes:
>> "All users must do a manual upgrade." : #manual is missing at the end of
>> the link.
>
> I've noticed this too while preparing 4.0, and then:
>
> - Initially I added #manual as you're suggesting, that seemed pretty
> much obvious. But then I noticed that doing so would make users
> skip the intro on the top of the destination page, which is not
> ideal. So I've dropped this change.
>
> - Then, on the destination page I turned the "manual" and
> "automatic", that are in bold in the intro, into links to the
> corresponding sections. But then I realized that there's a table of
> contents just a few lines below, so we already have links.
> So I've dropped this change too.
>
> ⇒ All in all, I could find no simple way to improve the situation
> without regressing elsewhere, so I gave up.
>
> sajolida?
Thanks A LOT for pointing this out. I think it's a mistake and that we
should point to /doc/upgrade#manual. Fixed in 9f20d30b16.
That's what I did for all previous release notes but I failed to apply
this to 4.0 because I was based on master at that time.
See cf41804ae7.
I also wondered about this URL while working on improvements on the
manual upgrade doc (#10885). Note that before this work, we were
pointing people to /upgrade, which had no information whatsoever about
what manual upgrades meant.
I wondered whether it was better to:
A. Have dedicated subpages for automatic and manual upgrades. So we
could point people directly to the page on manual upgrades.
B. Present both techniques in parallel on the same page.
By lack of strong arguments, I decided to go for B, which was closer to
what was already implemented. It's not a super good practice to point
people to anchors down a page (or even to use anchors), but:
- If we pointed people to a subpage only for manual upgrades it would
have pretty much the same text.
- It might be helpful to present both techniques in parallel on the same
page. Note that we refer to "automatic upgrade as described above".
I'm open to hear more arguments and do more work on this part of the
doc. Now is a good time since it's all still pretty fresh in my mind :)
--
sajolida
Tails —
https://tails.boum.org/
UX · Fundraising · Technical Writing
