[Tails-dev] Comments on Tails documentation

Delete this message

Reply to this message
Author: intrigeri
Date:  
To: tails-dev
Subject: [Tails-dev] Comments on Tails documentation
Hi,

during the low-hanging fruits session today, velope had a few
suggestions for us. Most of the above is copy'n'pasted from IRC, and
most credits should go to velope.

doc/first_steps/manual_usb_installation/linux
=============================================

It seems weird that we feel it's needed to instruct the user to type
Enter after the *last* command-line, but not after the others.

If it's needed, then that should probably be documented on top of
the page. Else, perhaps that could be removed.

doc/first_steps/bug_reporting
=============================

describing screenshot content?
------------------------------

under "Write the report", the 5 bullet points add nothing useful to
the screenshot and can be removed (or moved to a "alt" attribute).

but IIRC, it's bad doc practice to rely on info that's written on
a screenshot only. The screenshot should only confirm that you're on
the same page as the writer.

velope answers: ehh, i agree about that for formal writing, but
i suggest brevity wherever possible. the image alt-text point is
important, of course.

About giving us an email address
--------------------------------

We're told that:

the "About giving us an email address" section would seem to be
sarcastic and increase worry without a clear point. people understand
"optional email". if you still want some text, maybe "Giving us an
email address allows us to contact you to clarify the problem,
although it also provides an opportunity for eavesdroppers to confirm
that you are using Tails."

Looks good to me.

same situation with not-strictly-necessary text and alt-text: "Once
your email has been sent correctly ..."

Same as above, will need to be decided globally.

"In those cases, you can also send your bug report by email." -- a bit
confusing, since WhisperBack is email. maybe "... email your bug
report directly" (with existing hyperlink)

I tend to agree.

How to write a useful bug report
--------------------------------

We're told that:

and finally, about "How to write a useful bug report", sigh.
however true it all is, it's terrible to expect readers to browse to
an off-site page full of ESR preachy verbosity

if you believe it's really important, the page should directly have
the summary (but in no more than 30% of the linked-to summary text),
and provide the link as a credit or "for more info" reference.

I tend to agree.

doc/encryption_and_privacy/manage_passwords
===========================================

We're told:

first thing i noticed is that it might be good to have the usual
warning/info/hyperlink about choosing a strong passphrase, since
obviously it will be protecting other passwords

May make sense. Any relevant URL we could point at? Or do we consider
that the LUKS encryption is enough? This would be consistent with not
caring about the encryption used by KeePassX to start with.

Also:

"To learn more about KeePassX, read the official KeePassX user
guide." -- useless link to a one-line text nearby

and:

i find the use of bold text in the intro section to be distracting,
though i understand the motivation. if used generally as a house
style, i don't really object, but i don't recall that it is, and my
personal reaction is that it is not a plus.

Cheers,
--
intrigeri
| GnuPG key @ https://gaffer.ptitcanardnoir.org/intrigeri/intrigeri.asc
| OTR fingerprint @ https://gaffer.ptitcanardnoir.org/intrigeri/otr.asc