Re: On Documentation

[Ryan McDougall <NQG24419 nifty com>]

On Fri, 2004-23-07 at 08:47 +0100, Mark McLoughlin wrote:
> Hi Federico,

> 
> 	This is similar to i18n, and to a lesser extent a11y. We don't expect
> hackers to come along with new modules translated into 40 different
> languages, nor do we expect them to come along with fully accessible
> software. In the case of i18n, we have a sub-project which takes
> responsibility for that work and, for a11y, a sub-project which supports
> hackers in making their software fully accessible. We don't expect this
> stuff done upfront, but we do expect that new module maintainers be
> amenable to working with the sub-projects to get this stuff done in a
> timely manner.
> 

I don't believe the analogy is complete. Anyone with basic understanding
of computers and good understanding of two languages can do l18n, but in
many cases proper documentation requires a far deeper understanding of
the what program does and how; understanding that only the developer may
have. Especially of brand new programs, where there may not be a
preexisting understanding or context.

In that light I think there should be some *basic* documentation
demands: a couple page intro or overview (purpose, motivation, features,
etc.) document that other documenters can work off of to get up to
speed.

Other than I agree with the spirit of everything else you've said here.

> 
> Cheers,
> Mark.
> 

ps. API documentation should be made a larger issue now that GNOME is
stabilizing.

Cheers,
Ryan