Re: [Tails-dev] [Tails-l10n] Please review doc/experimental

Delete this message

Reply to this message
Author: sajolida
To: The Tails public development discussion list
Subject: Re: [Tails-dev] [Tails-l10n] Please review doc/experimental
> hi,
> sajolida wrote (03 Apr 2012 19:25:56 GMT) :
>> I already pushed to the doc/experimental branch a first batch of
>> docs for the upcoming release.
> Great! I reviewed all these new pages, liked it very much, and have
> a few minor fixes I should push.
> General note: it seems like these new pieces of documentation contain
> many links to numbered sections or sub-sections in other pages, such
> as "startup_options#index2h1". This seems very fragile to me: I doubt
> many of us will think of grep'ing through the wiki to adapt such links
> after doing a change that shifts section numbers. IIRC there's an
> ikiwiki plugin (maybe in contrib/? maybe written by pabs?) that allows
> to give section headings *named* anchors, in a way that I don't
> precisely remember, but that might help solve this problem.

Yes, I'm aware of that issue and I already tried this plugin
(headinganchors) to solve it. It is not configurable and creates anchors
like this `id="Warning_about_USB_sticks_and_solid-state_drives"`. I
don't like it for the following reasons:
- the text of the head might as well change, such errors would become
broken links in the wiki, but there might be external links as well
- the URL can become super-long and mixed in case, but that's a
aesthetics problem I guess

Another option would be to create anchors by hand when needed. But then
the anchors would not be created automatically for every headings. We
could do:

<a id="anchor"></a>


<h1 id="anchor">Heading</h1>

I'm not sure which option is the best, the plugin or the handmade
anchors. What do you think?

>> - doc/first_steps/usb_installer
>> This does only document the "Clone & Install" option so far.
>> How important do you think it is to document the other options in
>> time for Tails 0.11?
> I think the upgrade options can be postponed to right before 0.11.1.
> But we don't know how far from 0.11 this time will be,
> so I suggest writing these bits before it's a real emergency.

Ok, I'll try to do it for 0.11 if I have time.

>> - doc/first_steps/startup_options
> The screenshot does not display the widgets that allow the user to
> choose their preferred language and keyboard layout.
> Is this intentional?

Nope. But I double-checked and it doesn't appear on my virtual machine!
Maybe that's a side effect of the "VirtualBox guest modules are only
built for amd64" bug. I'll try again with the RC1 once I got one.

>> - doc/first_steps/startup_options/administration_password
> I'm not convinced by "to start Tails" in "Then click on the Login
> button to start Tails". I've seen a more accurate reference to the
> GNOME Desktop in some other new page, so I guess we can allow
> ourselves to write something less wrong here too :)

Done, I changed it to "start the GNOME Desktop".

>> - doc/first_steps/persistence/warnings
> When I read this:
> Remember also that secure deletion do not work as expected on USB
> sticks. See the corresponding documentation. Read how to delete the
> persistent storage instead.
> I think this suggests the "delete the persistent storage" page deals
> with secure deletion of that storage area. However, the first set of
> instructions given on that other page "choose Applications ▸ Tails
> ▸ Delete persistent storage, and click on the Delete button." does not
> support secure deletion yet, and the other sets of instructions either
> let me totally doubtful, or just don't work. See other problems in
> this area later on.

Ok, see 29ad316.

> About "The programs included in Tails are [...] audited for their
> security. This may not be the case of all the packages available in
> Debian": the way the "security" word is used here results in
> a sentence that is largely overstating what we are really doing.
> And follows "Other programs than the ones included in Tails may be
> subject to security holes that Tails do not protect you from", which
> is oversimplifying as well IMHO. Maybe go beyond the binary "security"
> flawed concept and explain that:
>   * Even "secure" software may be unsuitable to use in an anonymity
>     context (e.g. leaks IP address).
>   * Tails is an integrated system and injecting random stuff into the
>     mix may make the end result behave in totally unpredictable ways
>     that may, or may not, match the expectations one puts into Tails
>   * Installing additional packages is likely to turn your customized
>     Tails into something Tails developers cannot, or don't want to,
>     support.

What about:

« To protect your anonymity and leave no trace, Tails developers select
and configure with care programs that work well together. **Installing
additional programs may introduce unpredictable problems and may break
the protections built-in Tails.** Tails developers may not want or may
not be capable of helping you to solve those problems. »

> Is "permanent storage" used on purpose?

Not at all. I corrected all of them.

> "Only the files that you specify are stored." --> I'd rather say "the
> files and folders".


>> - doc/first_steps/persistence/configure
> "and open the Permanent folder" --> maybe you want us to change this,
> but currently, it's called "Persistent". The rest of this paragraph
> gets it right.

Of course.

> "Note that those packages are not automatically reinstalled when
> starting a new Tails working session." --> I suggest stating why one
> may want to activate this feature, in addition to its limits. Same for
> the next (APT Lists) feature.

Done, see b0bd883.

>> - doc/first_steps/persistence/use
> Looks like "the Permanent folder" strikes back.
>> - doc/first_steps/persistence/delete
> "Creating a new persistent storage on top of an old one makes it hard
> for an attacker to recover the files of the old persistent storage
> using data recovery techniques" --> Why? Because you suppose the old
> LUKS header to be overwritten by a newer one? If this is the only
> reason, I don't think we can seriously base anything on this. E.g.
> the modern partitioning tools we're using (namely: udisks) try to be
> clever wrt. sector alignment, and e.g. I would not bet Wheezy's udisks
> (in Tails 2.0), will create a new persistent storage exactly at the
> same place as Squeeze's udisks (in Tails 0.11) did.

Ok, you're right. Please see 301e40b.

> 1. Erase Tails
> 2. Securely clean all the available disk space
> --> I think #2 only works if there's a filesystem on the target USB
> stick, which is not true after following #1.

Ok, I see two ways of solving that:

1. Add a step that create a partition with a FAT file system after
erasing Tails. That can be done with the Disk Utility in Linux and it
seems like some versions of diskpart can format partitions too [1]. That
would also makes sense since when you buy an empty USB stick it usually
comes with a FAT filesystem and user might expect this from our claim
that erasing Tails from the USB stick allows to « use it for something
else ».


2. Add a step linking to "Create an encrypted volume" on the whole USB
stick before doing "Securely clean…" and be done with it.

>> While writing the doc on the persistent storage I also felt the need
>> to maybe work in better collaboration with the people writing the
>> GUI. It would be good to make more consistent the terminology and
>> style between our custom GUI and our documentation.
> Sure. Feel free to suggest whatever improvement you can think of.
> I did not know one may use the "storage" word as if it can be counted,
> as in "create a persistent storage". I thought a "storage volume",
> "storage area" or "storage container" can be counted, but *some*
> storage cannot. Did you double-check the (more concise) way you are
> using it is correct? If it is, I'm happy to adapt the GUI accordingly.

You're right again. It's not correct to say "a persistent storage". I
decided to use that term instead of just "persistence" because I thought
it was better to talk about a somehow concrete object than a more
abstract notion.

Maybe I can replace it by "persistent volume". That's the term used by
the Disk Utility and we already used it in "Create and use encrypted

>> But I'm not sure whether the timeline still also us to do so now
>> that we passed the deep freeze.
> From the release process side, I think improvements in terminology and
> style consistency can still be pushed into the various new GUI.
> Great work!