[prev in list] [next in list] [prev in thread] [next in thread] 

List:       tails-dev
Subject:    [Tails-dev] documentation contribution process too bureaucratic?
From:       adrelanos () riseup ! net (adrelanos)
Date:       2013-03-15 17:25:26
Message-ID: 51435986.1050807 () riseup ! net
[Download RAW message or body]

sajolida at pimienta.org:
> 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.

Yes, agreed. That is a good compromise. In wikipedia they (used to) have
a feature called sighted versions / flagged revisions. In essence,
causal visitors will see by default the reviewed (by admins) version and
contributors can work on a "fork". When the "fork" is ready and admins
had time, they call it sighted and it goes live. Not sure you ever saw
it, by in my opinion it had a real good ui for all participants. - That
may be the best solution.

> 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.

Ok, good point, I didn't consider this.

> 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.

Isn't perfect as the sighted revisions feature, because causal readers
only see "only admins can edit" and don't know anything about /todo.
Non-admins also can't easily get the wiki markdown so they can improve
it. (There is no such feature as get wiki source if not allowed to edit,
can only get it from git, which very few people will do.)

Still, it's a huge improvement.

>> 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...

>From my wiki experiences it can say it seldom happened and if only about
minor details. I accept that.


[prev in list] [next in list] [prev in thread] [next in thread]