# Preface

The GNOME Documentation Style Guide provides guidelines for authors who want to contribute to the GNOME Documentation Project (GDP).

## About This Guide

The goal of the GNOME Documentation Style Guide (GDSG) is to provide a framework for contributors to write good documentation. The GDSG also helps authors to write consistent documentation, so that users can expect certain structures and conventions in GNOME documents.

This style guide discusses basic principles of clear, concise writing so that users can achieve the maximum benefit from GNOME documentation. The guide also provides standards for common terms and concepts. The guide provides recommendations rather than absolute rules. However, in all parts of the user interface, including documentation, consistency is a virtue. When you write GNOME documentation, try to follow these guidelines as closely as possible. Users benefit from the consistent application of the guidelines in this guide.

This style guide is primarily for authors contributing documentation to the GDP in English. Although you can apply many of the guidelines in this book to all languages, there some guidelines that are specifically for English-language usage.

## What Is in This Guide

This guide contains the following sections:

Section | Summary
--- | ---
| Introduces basic concepts of technical documentation.
| Describes how to use different types of information structures.
| Provides advice and examples about how to use specific parts of grammar.
| Provides guidelines to cater for the most common problems encountered by translators of technical documentation.
| Outlines some tips about how you can review and improve your writing.
| Describes basic index requirements and indexing techniques.
| Describes how to write about GNOME user interfaces.
| Discusses readability issues, and gives some ways to assess readability.
| Discusses the needs of disabled users of technical documentation.
| Provides style guidelines for screenshots.
| Covers essential legal topics in GNOME documentation.
| Provides a comprehensive list of agreed terminology for use in GNOME documentation.
| Provides a list of standard units that appear in GNOME documentation, or in the GNOME Desktop.
| Provides a list of unfamiliar language terms that are used in this guide.
| Provides examples of the information design building blocks discussed in .
| Lists contributors to this guide.

## Who Should Read This Guide

Different parts of this guide are of different levels of interest to writers, depending on your level of experience, as shown in the following table. The key to the table is as follows:

* | You are probably familiar with this material. You only need to refer to this material for reference.
** | This information is of interest to you, however other parts of the guide are probably of more immediate interest. You can read these sections when you have time.
*** | This information is of immediate interest to you.

Section | New Writers | Experienced Writers
--- | --- | ---
| *** | *
| *** | *
| *** | ***
| *** | ***
| ** | **
| ** | **
| ** | ***
| ** | **
| ** | ***
| ** | ***
| ** | **
| *** | ***
| *** | ***
| ** | *
| *** | *
| * | *

## Associated Documentation

The following documentation is also associated with writing GNOME manuals:

- GNOME Handbook of Writing Software Documentation

- GNOME Human Interface Guidelines

## Related Documentation

See also the following documentation relevant to GNOME documentation:

- DocBook, The Definitive Guide, Norman Walsh and Leonard Muellner, O'Reilly & Associates, Inc.

- The Elements of Style, William Strunk Jr and E.B. White, The Macmillan Company

- Read Me First! A Style Guide for the Computer Industry, Sun Microsystems, SunSoft Press

## Reference Sources

The following reference sources are relevant to the guidelines in this guide:

- American Heritage Dictionary

- Chicago Manual of Style

- IEEE Computer Society Style Guide

- New York Public Library Writer's Guide to Style and Usage and other style guides in print and online.