Re: Improving GNOME docs...

[Andy Oram <andyo oreilly com>]

I've  been traveling and I apologize for taking so long to write on
this thread. I had a chance to look at some of the web pages people
have been pointing to in emails. You've got a strong base to work
from.

I'd better start out with a warning: I can't guarantee that O'Reilly
will publish a print book on GNOME development. I'm not sure you
should aim at producing materials that would flow nicely as a 400-page
(or whatever) print book. A well-interlinked collection of short
tutorials, reference material, and examples, updated frequently, might
meet your developers' needs better. But if we can collaborate and come
up with great documentation, maybe O'Reilly will indeed publish it. Or
some other publisher, such as Prentice Hall (is Bruce Perens still
working on his series?).

Quizzes:

  Certainly, writing and taking quizzes should be pleasant and
  voluntary.  I'm suggesting we just try it. I'm hoping feedback from
  quizzes can be so useful that developers are excited about writing
  them. (Remember, the people who write the documentation might not be
  the best people to write the quizzes.)  Quizzes should be just a few
  questions.

  I think it's pretty clear, in theory, that the best way to determine
  whether a document is useful is to watch the user go back to work
  and see whether he produces good code. But who can do that? It's not
  a trackable and measurable way to assess documentation. I hope
  readers find the quizzes useful to assure themselves they've
  understood the documents.

Where to start?

  There are many levels on which you can improve documentation. As an
  editor, I like deep approaches--asking what order people need to see
  information, how to provide mental models, etc. But we could use
  evidence to tell us whether deep rethinking of documents is more
  useful than simpler and cheaper fixes, such as:

  * Just improving the formatting and eliminating typos, grammatical
    errors, and other impediments to easy reading.

  * Producing better cross-references. (You've obviously done a lot of
    work to help guide people through a huge set of docs.)

  * Standardizing approaches to layout and organization so readers get
    used to the approaches and can find information more quickly. (I
    like the Documentation Style Guide a lot, and I wonder whether
    there would be any benefit to extending the guide to cover
    organization on a larger scale.)

Andy