Re: [Tails-dev] documentation contribution process too burea…

Delete this message

Reply to this message
Author: sajolida
Date:  
To: The Tails public development discussion list
Subject: Re: [Tails-dev] documentation contribution process too bureaucratic?
On 14/03/13 19:38, adrelanos wrote:
> Hi!
>
> I made the assumption, that you'd like to have more people improving
> documentation and thought may like to get feedback if someone feels
> that something prevents people from contributing, like I do.


Yes, that would be great to have more people writing documentation.

> Taking this as an example todo item:
> https://tails.boum.org/todo/document_timezone/
>
> Looks fairly trivial to me. I don't know why this even requires a todo
> item. You could just edit it in place.


Sure. I guess it's not done yet because the people who have been writing
documentation are spending most of their volunteer Tails time busy with
other things. That's a shame indeed.

> It seems to me, you want, that someone creates a git branch with the
> proposed changes, you'll discuss, revision, discuss etc. and finally
> bring it online. That seems overkill to me and people who could be
> sufficiently motivated to write such kind of documentation, I guess
> many users, are not willing to learn git and to go through a
> bureaucratic process.


Right, that's what is being described in /contribute/how/documentation
so far. I'm sure that can be improved.

> My suggestion is, such changes can be made in place. The other editors
> subscribe to changes and if they dislike something, they improve it
> right in place. Naturally, most times a good version develops. This
> works well for different wiki. Doocracy.


I disagree with you on this. Having a freely editable documentation
would imply more work on the shoulders of the people who are already
working with scarce human resources. Namely:

1. The core team. The way we document things has serious security
implications. People should be able to trust the Tails website as much
as they trust Tails itself. So having a freely editable documentation
would require us to do permanent checks on all the commits in order to
catch possible security issues. A much more reliable way to do so it to
be open to contributions, review them and publish them once they are
mature. Call it bureaucracy if you want, I call it collective process
and quality assurance.

2. Translators. Tails pretends to be multilingual. Of course, if people
do a good job, you can see incremental edits as incremental improvements
over a document; when working with a single language! But when you have
translations involved, an incremental edit in the original language
automatically degrades all the translation until they are updated
manually. So you're loosing work, and downgrading the documentation
every time. No good for translators, no good for users.

But here is a proposal that might please you. The /todo section is
freely editable on the website. So we can propose contributors to
elaborate their proposals directly in the ticket corresponding to the
issue. For example, if you want to work on /todo/document_timezone,
please do it right there. Then that could be collectively and
incrementally reviewed and improved. Once the documentation is mature
enough it could be published in the /doc section and sent for
translation. I'd also prefer if people doing that subscribed to
tails-dev and coordinate the debates in there.

Would that proposal answer your concern? If so, I'm ready to add it to
/contribute/how/documentation.

> Well, and before an edit war starts, in rare cases where you want to
> undo something, you can still start a discussion and come to a decision.


I like it better when one don't have to undo and loose work...