osdir.com


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

[doc] installation guide maintenance


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.
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20200604/d26227f0/attachment.sig>