elouann:
> Dear all,
>
> the documentation to build the wiki offline within Tails was
> outdated[1], please review the following draft:
>
> http://git.tails.boum.org/elouann/tails/tree/wiki/src/contribute/build/website.mdwn?h=build-the-wiki-offline-within-tails&id=120ee6d7a5d865ce69f24a0c3cf7609c0a2fac5d
>
> Repository: http://git.tails.boum.org/elouann/tails/
> Branch: build-the-wiki-offline-within-tails
Woh! Thank you so much for taking this over! I see that you have no
Redmine account so I can't send my review there. Please consider
creating yourself one so I can move my nitpicking away from everybody's
mailbox :)
First of all, I pushed some stuff on doc/9081-build-website-in-tails. So
please fetch origin and maybe rename your branch this way (git branch -m
doc/9081-build-website-in-tails). It's closer to the way we usually name
branches and might prevent you some problems.
There here are my comments:
* The instructions would look better with numbering as we usually do for
steps. Can you try that? Then feel free to do this as well in the Linux
section that would benefit from a bit of refreshing. You're allowed to
improve the phrasing there as well as an extra exercise!
* I prefer small and shorter steps to bigger and more complicated one.
Here for example, what about saying, in step 2, to run two commands
(apt-get update, then apt-get install), instead of one with &&? That's a
detail of course :)
* Ah, and in the same step, why not use `sudo` instead of introducing
the concept of "running commands as root". We're in Tails so we know how
this behaves and this would save you the `exit`.
* Please use Docbook-style markup for things like file names. In this
case "Persistent" and "ikiwiki.setup". See
https://tails.boum.org/contribute/how/documentation/guidelines#index3h1.
In the case of the contribute section, I tolerate using the markdown
equivalent (`). But beware: not everybody in the doc team might do so :)
* Let's replace all occurrences of "wiki" by "website" shall we? It's a
shame that the script is still called "build-wiki" (this could be fixed
by the way...) but the idea that our website is a wiki is confusing for
many as you can't actually interact with it as a wiki...
* I'm wondering whether the concepts of "offline" or "local" would be
more appropriate to explain what's special about this version of the
website. The built version is equally relevant whether you are offline
or online and the real difference is that it's built on your computer
and only you sees it. But yes, that makes it an version accessible
"offline". I have no strong opinion and let you decide on this one.
* As a consequence, I feel like this page needs an intro. We're saying
"build the website" but I feel like we need to explain people why. What
is the result (maybe "a working copy of our website that you can
navigate and modify from your computer", "offline" or "locally")? And
that this is useful for people writing documentation or translators to
verify the result of their change before sending a patch. I would write
something about this at the very top of the page.
* Avoid saying "easy" and let people decide by themselves whether what
we propose is easy. In the case of "easy access to this page", I would
myself need to understand the use of it to be able to propose a better
phrasing. How do *you* use this link? I personally don't have one and
use bookmarks in Tor Browser.
* Other than that I added a bunch of simplifications with commits
120ee6d..be707e0. Please check whether you are fine with them.
* Also note that you mixed up unrelated commits in your branch. Namely
commits 114ec4f, a078471, b3a98c2, and 4d05f2d but hey, I'm so laid-back
that I won't even bother you about this :)
