On 06/04/13 17:20, intrigeri wrote:
> 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.
Cool, thanks a lot for all those comments!
> 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.
Removed with 553e74b. This is not a guide on using the command line.
> 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.
Removed the screenshot in favor of the text with feeb3cb.
> 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 here. See 5b5d708 and 2e24ad1.
> same situation with not-strictly-necessary text and alt-text: "Once
> your email has been sent correctly ..."
I'm not sure I understood that part of the comment.
> 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.
Corrected with 078b18c.
> 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.
Tried something with 8dcae06. But that's only 45 % of the original word
count :) Jokes apart, that can surely be improved, and ideas are welcome.
> 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.
Well, deciding that's covered by the LUKS encryption reports the issue
of the strong passphrase to the Persistence setup where there is not
link either.
If we cannot agree on an external resource to link about good password
practices I propose to create a ticket for that (ie. for finding a link,
not writing the doc).
> Also:
>
> "To learn more about KeePassX, read the official KeePassX user
> guide." -- useless link to a one-line text nearby
Removed with 82d47a1.
> 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.
I use bold in text to make it scannable.
See
http://www.nngroup.com/articles/how-users-read-on-the-web/.
But I agree that can also add distraction, and I'm surely not an expert
on that technique. I've already been using it, for example in:
https://tails.boum.org/doc/first_steps/persistence/warnings/
https://tails.boum.org/doc/about/fingerprint/
Do you feel the same issue affect those pages too?
In the case of KeepassX, the three things in bold are three strong
arguments in favor of KeepassX. They could also be presented as a dotted
list. For example:
« Using the KeePassX password manager you can:
- **store many passwords in an encrypted database** which is protected
by a single passphrase of your choice,
- **always use different and stronger passwords** since you only have
to remember a single passphrase to unlock the entire database,
- **generate strong random passwords**. »
Would that be an improvement?
