Re: On Documentation

[Mark McLoughlin <markmc redhat com>]

Hi,

On Fri, 2004-07-23 at 09:44, Ryan McDougall wrote:
> 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.

	That's a good point - it kind of ties in with the "should be amenable
to working with the sub-projects", but requires some upfront work by the
new module's maintainer.

	And to complete the analogy - this is like requiring new modules to be
pretty well internationalised and have l10n infrastructure in place.
Also, in terms of a11y, similar to requiring new modules to re-use
already accessible widgets rather than creating custom widgets and
making sure the software is at least fully navigable using a keyboard.

Cheers,
Mark.