Re: [Tails-dev] Documentation : proposed improvements

Delete this message

Reply to this message
Author: sajolida
Date:  
To: The Tails public development discussion list
Subject: Re: [Tails-dev] Documentation : proposed improvements
sam_tnoob@???:
> Hello,
>
> When installing tails for the first time yesterday, i was a bit lost in the documentation.
> Here's the path I followed : "Documentation" > "Get Tails". Here I get and verified the Tails image, it was OK. But then : "First steps with Tails". It's never said in the page "Installing onto USB stick" or "Manually install Tails onto another USB stinck" that it's now OK, that I can start Tails by rebooting on the USB stick. In the page "manually...", the last thing I read before troubleshooting is "The whole process might take some time, generally a few minutes. Be patient…".
>
> I see 2 ways of fixing that :
> 1. Only to these pages, adding "Now, you can [[start]] Tails" (redirecting to the page https://tails.boum.org/doc/first_steps/start_tails/index.en.html ) and, if needed "and [[install Tails]] to another USB stick from your fresh new Tails to activate persistence support".
> 2. More generally, automatically add a link below every page towards the next page in the documentation (following the order given in the index page).
>
> 'hope this helps,
>
> Sam.


Hi, sorry for the delay. Your email was still in my inbox.

I agree, sometimes it's easy to forget the obvious. There should be some
effort put into linking better the various pages of the documentation.
And the example you suggest is definitely true. Another issue was raised
in the past about the page "Trusting Tails signing key" and some people
said they didn't know what to do next.

I read with interest the documentation of the trail plugin for ikiwiki
but I'm not sure that this would solve everything. I think there could
be two different ways of linking pages together

One would be a mental path of doing things. For example, proposing to
read "Start Tails" after "Installing onto a USB stick". The other one
would be a logical ordering of the index of the documentation. For
example "Delete the Persistent Volume" comes right after "Enable & Use
the Persistent Volume" in the current index.

But those two paths might be different. The structure of the index of
the documentation should support the mental path but they cannot always
perfectly match. For example you might not always want to "Delete the
Persistent Volume" right after creating it ;)

So maybe we should use different widgets to provide those two features.

My plan was to use the trail plugin to provide navigation through the
index. But on top of that we will probably also need to add manually
some entries to support the mental path whenever the navigation is not
enough (like in your example).

Those would be some kind of "See also" cross-references [2]. Those could
be graphically supported by icons like the ones we're using for 'bug',
'warning' and 'note' so far (see [3] for example).

Does that makes sense?

[1] http://ikiwiki.info/plugins/trail/
[2]
http://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html#indexing-6
[3]
https://tails.boum.org/doc/first_steps/persistence/configure/index.en.html

--
sajolida