Style Guide completion

[David Ottina]

On Thu, 2005-08-04 at 19:26 +0800, Jerome Gotangco wrote:

> Many thanks to Jeff Schering for leading this wonderful piece of work.

Yes, many thanks!

> For those currently with svn access please review (or even contribute
> further) the document! 

I wonder if it is worth adding a little more introductory guidance near
the beginning. I realize the Gnome guide covers this, but for the sake
of convenience...

Perhaps something like:

Users need to find information quickly. People don't read documentation
as much as they scan it for solutions to their immediate problem.
Writing and presentation styles that seem redundant in essays or other
texts are often helpful to people scanning for information.

      * Clear – Write short, active sentences using everyday vocabulary.
        Maintain a visual separation between page elements.
        
      * Concise – Minimize content so it can be found and remembered.
        Keep pages short, modular and focused on a single topic.
        
      * Consistent – Refer to one thing or idea with the same word
        throughout the page. Use headlines, lists and emphasis to signal
        importance.
        
Match Writing Style to Purpose
Use a writing style that fits the text's purpose. The most useful styles
in documentation are explanatory and procedural. Explanatory writing is
for special language or concepts that users need to understand a
procedure. Format explanatory text in paragraphs.

Procedural writing is good for telling readers precisely what steps they
must take to complete a task. Write procedural text as numbered lists.
Tell users what to expect when they've finished.

Best,
David