Re: Getting the info

[Shaun McCance <shaunm gnome org>]

On Tue, 2006-04-04 at 21:30 +0100, Joachim Noreiko wrote:
> Recent bug report mentions in passing:
> 
> This search was performed because there was no help
> text for the "Editable menu accelerators" checkbox in
> the "Menu and Toolbar Preferences" config dialog
> 
> How on earth is a docs writer supposed to
> a) notice thie presence of a new feature such as this

Actually, it's a very old feature.

> b) find out how it works in detail?

We can help out with both substantially by having actual
technical reviews of all our documentation.  Developers
should read over all the documentation and:

1) Make note of what's missing
2) Make sure everything is correct
3) Think about how they can improve their interfaces
   and user interaction in light of how extensively
   we needed to explain it to normal people.

Professional tech writing firms and departments always
have technical reviewers (and good copy editors, another
thing we lack).

Here's a reasonable process:

1) Start with the existing documentation.
2) Get a list of user-affecting changes and additions
   from the development team.
3) Write.
4) Get some peer reviews.  These should focus largely
   on content organization, although they may also
   address language usage and markup.
5) Write.
6) Get a technical review from the developers or a
   dedicated technical reviewer.  For cross-module
   documents like the User Guide, you may need a few
   technical reviews from different people.
7) Write.
8) Have the technical reviewers review your changed,
   to make sure all their concerns were addressed.
9) Get a review from a copy editor to check language
   usage and markup.  This could come from two people:
   one for language usage and one for markup.
10) Write.
11) Declare the document final and let the translators
    have at it.
12) Translators should also try to get reviews for
    language usage.

Phew.  That sounds a lot harder than what we do now.

--
Shaun