Re: Nine Months in Six Months

[Alan Horkan <horkana maths tcd ie>]

On Sat, 9 Sep 2006, [ISO-8859-1] BJörn Lindqvist wrote:

[...]

> * Five months were developers play and pretty much destroy all the docs we make.
> * Four weeks were we can undo the damage caused and make GNOME understandable.
>
> Maybe this problem can be solved by elevating the documentations and
> the translations status in the project? For example, patches are very
> seldom accepted if they introduce regressions in the software. But
> regressions in the docs aren't counted in the same way. New code very
> often changes applications behaviour so that the manual becomes
> invalid. What if the documentation and translation regressions were
> counted in the same way as code regressions?

> To me, that makes sense. An untranslated string is just as annoying as
> a frequently segfaulting program. So lets treat the problems the same.
> Code that changes behaviour shouldn't be committed unless the
> documentation is updated.

This can be mildly annoying but it is one of those things you know you
should do.  If the documentation is hard to write is often a strong
indication that the new feature is hard to use and the design might need
to be improved.  I have a lot of respect for Gnome Games which had a
policy of requiring basic documentation with new Aisleriot changes.  The
task made easier by the fact that most of the new documentation was really
a variation on what was already there.  Callum was nice about and
civilised about the requirement for documentation which is important
because documentation we wouldn't be hurdle or barrier to contribution.

It would be great if the documentation team could be elevated to the
status of documentation editors who would help review improve the rough
descriptions provided rather than having to write from scratch.

-- 
Alan H.