Hi sajolida, hi all,
sajolida <sajolida@???> :
> 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 :)
Thanks for this review!
Indeed, my account does not appear on Redmine. I sent an email to the
sysadmins.
> 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!
Approved, I added some numbering
> * 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`.
I agree with the shorter steps. I split this command, but the drawback
is that one has now to enter the administration password *two* times.
No big deal, though.
> * 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 :)
:)
Applied, hopefully the right way.
> * 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...)
Agreed and applied in the commit 7546e43:
I renamed the file "build-wiki" then did grep the whole source code and
modify each occurrence, except in the folder
"config/chroot_local-includes/usr/share/doc/tails/website" which is, I
think, automatically generated.
Is this script called from somewhere else?
> * 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.
About "offline/locally", I have no strong opinion too.
The introduction is left undone, no inspiration right now.
> * 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.
I'm absolutely 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 :)
:) Thank you!
I renamed my branch, so the last commits can be reviewed in
elouann doc/9018-build-website-in-tails commits ab3cb2b..7e0cba1
Cheers,
~ elouann
