Re: [Tails-dev] Please review draft documentation for IUK

Nachricht löschen

Nachricht beantworten
Autor: sajolida
Datum:  
To: The Tails public development discussion list
Betreff: Re: [Tails-dev] Please review draft documentation for IUK
intrigeri:
> First, I'm confused. You wanted me (with pretty good reasons) to
> rename "Tails Upgrader" to "Tails Incremental Upgrader", so I did that
> a few weeks ago (and, well, it was quite painful). And now the doc
> refers to "Tails Upgrader" everywhere. What's wrong?


When I said that I thought the user would have to understand and decide
when to do a incremental upgrade and when to do a full upgrade.

But with the IUK being automatic, the user is now taken into the
incremental upgrade without having to take that decision or understand
the conceptual difference between both. The IUK is started
automatically, so that's what I called the "automatic upgrade", and if
this doesn't work, then you can do a "manual upgrade". And we avoid to
use "incremental" which is slightly more jargon.

I called "Tails Upgrader", the piece of software that leads you through
that process, to either do the upgrade or tell you that it is not
possible and you should do it manually.

I didn't think this was much work from you. I thought you basically
renamed the launcher (d54025d). And that I would adjust the
documentation and strings presented to the user.

Sorry, for changing my mind. What do you think of the terminology as it
is now?

>> If you use Tails from a DVD or if your Tails device was not installed using
>> Tails Installer, it is not possible to upgrade and you need to follow our
>> [[installing instructions|download#media]] again with the new ISO image.
>
> s/installing/installation/ ?


Done.

>> - If an error occurs while checking for available upgrades:<br/>
>> [[file:///usr/share/doc/tails/website/doc/upgrade/error/check.en.html|upgrade/error/check]]
>> - If an error occurs while download the upgrade:<br/>
>> [[file:///usr/share/doc/tails/website/doc/upgrade/error/download.en.html|upgrade/error/download]]
>> - If an error occurs while installing the upgrade:<br/>
>> [[file:///usr/share/doc/tails/website/doc/upgrade/error/install.en.html|upgrade/error/install]]
>
> Links to file:///, really? This won't work for those who read this
> page online, outside of Tails.


I agree that looks a bit subversive but I had a rationale behind that.
We know that those pages are a bit special already: people are invited
to visit them from inside the error messages by typing the whole damn
URL in the browser. I wanted to allow people to reach them through the
doc as well, so they can consult them even without the error message in
front of their eyes.

I decided to use the same caption for those links that what the user
sees in the error message; which is the URL starting with file:///. (By
the way, I'd be curious to learn how many people know that a URL can
start with something else than http). But from the online website those
will point to the https:// pages as usually. It's only the caption that
has file:///.

Does that makes more sense somehow?

>> In that case, <span class="application">Tails Installer</span> allows you to
>> manually upgrade a USB stick or SD card to a newer version of Tails.
>
>>   - [[Upgrade by cloning from another device|upgrade#clone]] which already
>>     runs a newer version of Tails
>>   - [[Upgrade from an ISO image|upgrade#from_iso]] of a newer version of
>>     Tails

>
> Needs some linking words between the first sentence and the bullet
> list, maybe?


Fixed. bullet lists need to be introduced by a sentence ending with ':'.

> In doc/upgrade/error, I read "Check your network connection, and
> restart Tails to try upgrading again." but this is not really about
> "upgrading", as most likely there is no upgrade available. "Checking
> for available upgrades", instead?


Indeed. I adapted the sentence in doc/upgrade/error/check.

I'm offline right now and will push all that later on.