Golden Rules

This section contains some basic style guidelines. Subsequent chapters of this book expand on these guidelines to give more detailed guidance.

Golden Rule 1
  • Limit each sentence to less than 25 words.
  • Limit each procedure step to 23 words.
Example Under normal operating conditions, the kernel does not always immediately write file data to the disks, storing it in a memory buffer and then periodically writing to the disks to speed up operations.
Rewrite Normally, the kernel stores the data in memory prior to periodically writing the data to the disk.

Golden Rule 2
  • Limit each paragraph to one topic.
  • Limit each sentence to one idea.
  • Limit each procedure step to one action.
Example The Workspace Switcher applet helps you navigate all of the virtual desktops available on your system. The X Window system, working in hand with a piece of software called a window manager, allows you to create more than one virtual desktop, known as workspaces, to organize your work, with different applications running in each workspace. The Workspace Switcher applet is a navigational tool to get around the various workspaces, providing a miniature road map in the GNOME panel showing all your workspaces and allowing you to switch easily between them.
Rewrite You can use the Workspace Switcher to add new workspaces to the GNOME Desktop. You can run different applications in each workspace. The Workspace Switcher applet provides a miniature map that shows all of your workspaces. You can use the Workspace Switcher applet to switch between workspaces.
Tip Plan the order of paragraphs before you start writing. Decide which topic you want to cover in each paragraph.

Golden Rule 3 Use explicit examples to demonstrate how an application works. Provide instructions rather than descriptions.
Example There is a text box that you can use to find out the definition of a word.
Rewrite To request a definition of a word, type the word in the text box, then click on the Lookup button.
Tip Do not apply this guideline too rigidly. Sometimes you must explain how software works to support your how-to examples.

Golden Rule 4 Write in a neutral tone.
Example The applet is a handy little screen grabber.
Rewrite You use the applet to take screenshots.