This document is still a work in progress, but it would be nice if we could all start pretending it was the real thing... ;)

The state of play

  • The DocumentationProject (GDP) is operating on a skeleton crew, and has been for several cycles.

  • Many docs are out of date
  • We don't have the resources to keep pace with changes in existing applications or new ones

and of course

  • GNOME users depend on documentation to use GNOME
  • GNOME developers depend on documentation to work on GNOME and GNOME applications

Policy

Comes in two parts:

What the docs team does for you

The GDP works on all sorts of documentation: user guides and manuals, and developer documentation. There is a list (not yet complete) of the documents we maintain at DocumentationProject/Documents.

We would like (though we're not able to) have a specific person assigned to each document that we maintain, who can work in parallel as a member of the corresponding application's team. (See the section 'Recruit' below...)

And we would still like the members of the application's developing team to be involved in shaping and writing the documentation.

What you can do for the docs team

If you would like the GDP to assume maintainership of your module's manual, there are several things we need you to do.

Firstly of course, you need to tell us ;)

Bugzilla components

Your module in bugzilla should have a component dedicated to the user manual. This should probably be called 'docs'. (For now. We're currently thinking about standardizing the name. Other popular choices include 'Documentation', which is fine too.)

We would like the default assignee of this component of your module to be this bugzilla dummy account:

This has several advantages: GDP members can add this account to their notification list on bugzilla, it's easy to get a list of all bugs that the GDP is concerned with, and it's future-proof.

The default QA contact can be anything you like. Many maintainers set the QA contact to themselves or their product's -maint dummy account so they can track documentation bugs easily.

Gnome-doc-utils

Set up GnomeDocUtils. This makes things easier for the doc writers and translators.

File bugs

Not all writers are able to build the latest Gnome from source. After freeze we are usually able to make ourselves a virtual machine image, but this has not been without teething problems, and in any case leaves us with very little time before release to document many changes which we're not always aware of. We'd like to get as much work as possible done before freeze, and during freeze we'd like to know what we need to look out for.

We would like you to file a bug against the user documentation component every time you make changes to your application's UI. You should include:

  • a brief description of what has changed is enough (though not a ChangeLog extract please: you might know what UI change is implied by 'Switched to using GtkBeanstalk', but we don't).

  • a mention of the bug number that your CVS commit fixed, if there is one.

If a GDP member needs more from you, s/he can set the bug to NEEDINFO.

Keep us informed

Generally, keep the documentation team informed of what's going on with your module. We can't promise to keep track of every roadmap, and not every project has one. If you're planning a complete overhaul of your application, for example, let us know early on, so we don't waste time updating the manual for an interface that's about to be binned.

Recruit!

As previously mentioned, we're thin on the ground at the GDP. If you have contributors interested in working on your documentation, please send them our way.


CategoryDocumentationProject

DocumentationProjectPolicies (last edited 2008-02-03 14:47:55 by localhost)