Re: [Tails-dev] doc: a bunch of remarks

Delete this message

Reply to this message
Autor: sajolida
Data:  
Dla: The Tails public development discussion list
Temat: Re: [Tails-dev] doc: a bunch of remarks
El 08/05/11 21:06, intrigeri escribió:
> Hi,
>
> I've had a look at the current state of doc-rework.
> I'll reply the specific point sajolida asked for in the dedicated
> threads, so this email is rather for anything that does not fit in
> there.
>
> ,----
> | /download
> `----
>
> I wonder if we should s/Latest release/Latest stable release/. What do
> others think?


I think that in the Tails development cycle as I've followed it for the
last few months there is always one and only one version people should
use. So I think that adding 'stable' is useless jargon.

Actually, I would be in favor of moving the "Release candidates"
paragraph out of this page. Since we're clearly saying that it should
only be used for testing I think it belongs to the "Contribute" section
instead of the "Download" section.

> I don't like that much the link to the ISO file because it adds one
> more manual step to the release process.
> About hash verification, again: shall we really update this page with
> new hashes when we release new images?
>
> More generally, this page seems to contain tons of stuff that should
> be updated on every release, which annoys me a bit. But well, if you
> feel like it makes downloading / explaining really easier, not the end
> of the world, but contribute/release_process shall be updated
> accordingly then.
>
> What worries me more is... what happens when PowerPC
> images come back?


I share your concern.

I was trying to avoid forcing people to go through Apache indexes like
http://dl.amnesia.boum.org/tails/stable/, click on the
"tails-i386-0.7.1" directory, find out that what they want to download
first is "tails-i386-0.7.1.iso", all that possibly going back to the
initial "Download" page to look for more info if you're not using tabs.
Sounds like a possible nightmare if pushed a bit to the extreme. The
less we need to explain the better for everybody.

But I recon that I could also sound like a nightmare for the people
doing the release. So a question I've been willing to ask for a while
without daring is: do you think I would be possible/a good idea to have
some code filling up that page at some point? It could be either:

- some code run at release time to fill up the ikiwiki,
- some code run by ikiwiki while compiling the pages (that sounds like
the cooler option but I had a quick look at the existing ikiwiki plugins
and I didn't find anything like this),
- some code run on the server side by Apache, eg. PHP, Perl, Ruby, etc.,
- some code run on the client's browser, eg. Javascript with graceful
degradation.

> The "Using the command line" way links to the .sha256 file on mirrors.
> For consistency with the above explanations (e.g. reliance on HTTPS)
> and with the next method ("Using Firefox"), I believe it should link
> to the same file hosted on *our* website instead. Am I misunderstood?
>
>> Older computers might not be able to start from a USB stick.
>
> I doubt such computers are able to run Tails at all => I'm in favor of
> removing this sentence.
>
> ,----
> | usb-install-for-linux
> `----
>
> GNOME Disk Utility might be an easier way to find the source /
> destination disks path.
>
> When cloning Tails USB->USB, if the destination stick is smaller than
> the source one, an error is likely to be displayed. The user should be
> explained this is not really a problem.
>
> ,----
> | links to anchors
> `----
>
> The now doc pages make heavy use of links to anchors such as
> doc/warning#index3h1. Since this relies on the titles numbering, I
> think this is much too error-prone and likely to be quickly
> outdated... I already found one such broken link just by browsing the
> documentation, hence this remark. When we need to link to a specific
> paragraph of a big page, I think a better way to go would be to split
> the big page into sub-pages and have the big one built using
> [[!inline]] from the sub-pages. (git grep'ing our wiki's source will
> provide a few real-world examples of this technique)
> => we can link to the subpage we want and easily notice broken links.
>
> Bye,


Agreed on all that.

--
sajolida