osdir.com


[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[doc] installation guide maintenance


On 6/5/20 1:35 AM, Jeremy Stanley wrote:
> On 2020-06-05 00:48:42 +0200 (+0200), Thomas Goirand wrote:
> [...]
>> Back at the time, the decision was made because some core
>> contributors to the install guide just left the project.
> 
> It wasn't just "some core contributors to the install guide" but
> rather the entirety of the documentation team, or very nearly so.
> The one or two people who remained barely had time to help maintain
> tooling around generating documentation and no time whatsoever to
> review content.
> 
>> It was at the time said that moving the maintenance to each
>> individual projects would scale nicer.
> 
> It scaled at least as well as the alternative, which was no longer
> updating the documentation at all. There were calls for help over
> many months, in lots of places, and yet no new volunteers stepped
> forward to take up the task.
> 
>> I am now convince that this is the exact opposite that has
>> happened: docs are maintained a lot less now, with lower quality,
>> and less uniformity. So I am convince that we did a very bad move
>> at the time, one that we shouldn't have made.
> [...]
> 
> Less documentation maintenance was inevitable no matter what choice
> was made. The employer of basically all the technical writers in the
> OpenStack community decided there were better places for it to focus
> that time and money. The only people left who could write and review
> documentation were the developers in each project. The task fell on
> them not because they wanted it, but because there was no one else.
> That they often don't find a lot of time to devote to documentation
> is unsurprising, and in that regard representative of most open
> source software communities I've ever known.

Yes, some people left. Yes, calls for help have been ignored. But still,
IMO, there was alternatives to destroying the install-guide, and that
wasn't the solution. Anyways, it's probably too late to go back, so
let's not continue discussing this. :)

BTW, where may I find that old install guide? Is there somewhere it can
still be seen online? I've searched for it and couldn't find it anymore.

Thomas