Golden Rules

Go to page content
Go to main menu
Go to the search field

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.

About