Re: [Tails-dev] [PATCH] Misc website/documentation fixes

Delete this message

Reply to this message
Author: sajolida
Date:  
To: The Tails public development discussion list
Subject: Re: [Tails-dev] [PATCH] Misc website/documentation fixes
Chris Lamb:
> Attached is the following:


Yeah! It's super cool to receive small fixes like this, especially as
people writing our doc (starting with me) are not native English
speakers and we'll always make linguistic approximations. So I merged
all this, thanks!

I'll do a bit of nitpick on some aspects of your commits, so you
understand better our workflow.

> commit a4cdb31408c9fea951b2a427d03491ce5ab3b8e5


Whenever we update an English string, the translations get marked as
fuzzy and disabled on the website. And, depending on the reactivity of
the translation team for each language they can remain broken basically
for ever in some cases.

So whenever I do changes that I believe only affect the format of the
English but not the meaning, I take the time to unfuzz the translations
as well. Here it's probably safe to say that this commit doesn't change
the sense of the sentence and different languages and different people
have different ways of using commas (for example, in German it's
mandatory here I think). This is not always 100% sure when talking about
languages that one does not understand but here, talking about the first
two strings on our index page, I thought it was worth it.
See c3a7ee2.

> commit 1973e1a98096d523fa0e797d09bb5eed54f6c6b8


This one introduced a broken HTML tag. To spot them, it's useful to
build a local version of the website as explained on [1] because ikiwiki
screams at you when it can't parse the HTML.

[1]: htts://tails.boum.org/contribute/build/website/

> commit 8ddec86444839484a4c1b51167af122bdca45394


That's the kind of fixes that are very hard to spot for non-Native speakers!

> commit de56a6e7598bab1faf8c2264e5d58d2cb9e92c2c
>
> Author: Chris Lamb <lamby@???>
> Date: Mon Nov 21 11:04:18 2016 +0100
>
>       Replace "You need" with "You will need" on upgrade overview.

>
>       This is the usual phrasing for "recipes".

>
>       Signed-off-by: Chris Lamb <lamby@???>

>
>    wiki/src/install/inc/overview.html | 2 +-
>    1 file changed, 1 insertion(+), 1 deletion(-)


I was not sure whether to merge this one but finally I did. In technical
writing we try to avoid using the future tense and stick to the present
tense as much as possible. Because for the user following the
instructions, she is in a succession of present actions and future tense
is also often unclear about when exactly in the future the thing will
actually happen. Here for example, one of the goal of the overview page
is to take some time for the user to make sure that all the "needs" are
fulfilled before starting with the instructions.

But since you're saying that this is the usual phrasing for "recipes"
and here we're presenting things like a recipe, I'll trust you that
saying only "you need" will look weird to native English readers.

> You can also merge from the "misc-documentation-fixes" branch of
> https://github.com/lamby/tails if that is more convenient.


Added to my remotes for next time :)