Re: Question about documentation

[Malcolm Tredinnick <malcolm commsecure com au>]

On Fri, Nov 08, 2002 at 10:42:59AM +0100, Stéphane Genaud wrote:
[...]
> as it is time for questions to candidates, i would like
> to know what are your positions on documentation.
> 
> >From answers to the 11 questions to candidates, i totally
> agree with Sri Ramkrishna who menshioned, for question  5),
> the lack of documentation as a weakness of Gnome.
> 
> I am not talking of the API documentation which is good enough in my
> opinion, but i do think we lack tutorial documents. 

We lack both and we have both, but not always in easily accesible places
that people can find quickly. Judging just from the GNOME mailing lists,
you are at least the second person in the past day to not realise that
some of the documentation you are after is shipped with the package
itself (see below).

> Look at bonobo for instance, and can you tell me, who (among
> newcomers to the gnome world) would be
> able to use or produce bonobo components from the documents 
> that can be found on internet ?
> Apart from the API (which is not helpful to begin) i could find
> only three short articles from Michael Meeks on IBM developerWorks [1] 
> and one document from Mathieu Lacage and Dirk-Jan Binnema [2].
> And when reading [2], you can legitimately wonder to what version it
> applies....

There is also Mathieu Lacage's excellent documentation that comes with
the bonobo-activation package. It is the API documentation for that
package with a lot of introductory text and a description of the big
picture.

> I do not want to be rude with people that have wrote bits 
> of documentation so far (i have myself participated to such effort)
> but i think it is time to deliver documentation and code at the same
> time. People on the board should consider the task of writing
> documentation as a first order issue, and ask hackers to participate
> in that effort.

This is not really a reasonable request, in practice. Some people are
coders, others are documenters, others are graphic designers, others are
accessibility experts and so on. Turn your question around and ask
whether a coder should also have to deliver good graphics, full
translations and fully accesible code all at the same time, or if they
could maybe get some help from some of the other teams in these areas.

It is not really reasonable to say that a coder also has to be able to
write good documentation. Writing any documentation takes a significant
investment in time and different skills from developing the code. The
fact that people like Michael and Mathieu (and many, many others) take
time out from their coding to also write articles is great, but it
should be an expectation.

What is required, as a number of people have pointed this out in their
answers to the questions, is a bit organisation in the form of pointing
out where the documents are available and then motivating people to
write documents to fill in the gaps.

There are megabytes of documentation available for GNOME (and I'm just
talking about up-to-date stuff here). The majority of that is user
documentation, but the developer side is growing. The steps that need to
be done are

	- make a decision that some stuff is out of date and remove it.
	  There is at least one list of this floating around and no
	  doubt there are others. Some of the old stuff cna be updated
	  at lower cost than a complete rewrite.

	- work out what developer documentation exists both within GNOME
	  projects and written by outside parties (e.g. the large number
	  of IBM Developer Works articles that have been written about
	  GNOME by both core developers and others).

	- work out what areas are not adequately covered and try to
	  motivate people to write documentation to fill in the gaps.

A lot of this does not need the board at all. It is already happening
within the documentation project. For the past year there has been a
strong focus on writing comprehensive user documentation. That has
really come together, combined with the supporting stuff like the
usability guide, the GNOME style guide, the glossary and so on.
Developer documentation has had a slightly lower priority, just because
there is so much to do (and the required knowledge for user
documentation is slightly lower). Now that there is a grasp on the user
documentation, the documentation project is starting to talk about
developer docs more and will hopefully continue to do so, especially if
people like you keep prodding them.

Note, also, that at least six of the people who have answered questions
so far have mentioned the importance of documentation and training
resources aimed at developers as of high importance to them. And most of
those people have already contributed towards that goal and will no
doubt continue to do so even if they are not elected. I think it's
pretty safe to say that all developers (not just coders) are aware of
this situation and working to improve it. There are only so many hours
in a day to do it in, is the problem. It's been encouraging to read the
answers so far, since it gives me the confidence that it doesn't matter
who gets on the board in this respect -- most people are aware that the
documentation still needs work.

Hmm .. somewhere along the line there I switched out of candidate mode
and into "go team" mode. But stuff it; that's the way I feel.
Documentation is important.

Malcolm

-- 
Works better when plugged in.