Style Guide completion

[Jeff Schering]

On 8/4/05, David Ottina <dotti at telenet.be> wrote:
> 
> 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.
> 

Hi David

Thanks! The style guide needs something like that. If you don't mind,
I would like to add it. I'm thinking a new chapter called "Information
Design" which would be Chapter 2. If you are familiar with DocBook and
would like to add it yourself, just send a patch to the list, or I can
add it myself if you prefer. Either way, let me know.

Cheers,
Jeff

-- 
GPG Key: 1024D/F23C67E8 2005-02-20 Jeff Schering <jeffschering at gmail.com>