Re: On Documentation
- From: Mark McLoughlin <markmc redhat com>
- To: Ryan McDougall <NQG24419 nifty com>
- Cc: Shaun McCance <shaunm gnome org>, Federico Mena Quintero <federico ximian com>, Desktop Devel <desktop-devel-list gnome org>, gnome-doc-list gnome org
- Subject: Re: On Documentation
- Date: Fri, 23 Jul 2004 09:54:34 +0100
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
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.
] [Thread Prev