Document Actions
Writing
Using consistent writing styles and textual elements will help standardize your document and make them easier to use for the reader. This is by no means a comprehensive list of style and text usage. If you are curious and want to learn more, look into The Chicago Manual of Style.
Writing Style
Tone, voice, tense, grammar, and choice of words (among other things) all make up part of a writer's style. Every writer's style is influenced most heavily by his or her personality. You may have noticed though that technical documents tend to have a very dry style to them. The goal for technical documentation is to convey information in a clear and concise way. By using the following style techniques, you can help make sure your document is understood.
Present Tense
Use the present tense of the verb in all sentences. Using the present tense shows the user clearly that this is the action s/he should take now (instead of in the future). Switching back and forth between tenses confuses the reader. Using present tense consistently helps the reader follow along the document and perform the steps in the order they are supposed to occur.
Action Words
Action words are verbs that describe what action the user should take. You may also know this as using the active voice when you write. An action word is simply something you do. We use action words when we want to direct the reader to do something. Below is a list of example action words that are commonly used to describe navigation. *
| Term | Use |
| Arrow Keys | Use to collectively refer to the left, right, up or down arrow keys on the keyboard. |
| Browse | Use browse through a list (database, document, and so on) not browse a list. |
| Click | Use click rather than choose or select, to refer to a user choosing or
selecting a command or option. Do not use click on or click at;
however, click in the window is acceptable. Click the button is also acceptable. |
| Close | Use close for windows, documents, and dialog boxes. For programs or network connections, use end or quit. |
| Deselect | Do not use. Instead, use cancel the selection or clear. |
| Dialog box | Always use dialog box and not just dialog or pop-up window. |
| Highlight | Do not use. Instead, use select. Refer to the selected material as the selection. |
| Icon | Use to describe a graphic representation of an object that a user can select and open. |
| Install | Use install when referring to hardware such as device drivers. Use set up when referring to software or components. |
| Key combinations | Use a plus sign to indicate key combinations such as shortcut keys and access keys. |
| Press | Use when pressing a key initiates an action within the program or moves the user's position. |
| Enter | Do
not use enter as a synonym for type, except to indicate that a user can
either type of click a selection, such as from a list in a box. |
| Type | Use type, not enter, to direct a user to type information that will appear on the screen. |
| Use | Use
in situations when press might be confusing, such as when referring to
a type of key such as the arrow keys or function keys. |
*Please note that this list is by no means the end all be all of words to use to describe navigation. They are simply examples of common usage in technical documents.
English Grammar
Learning proper grammar is not what anyone would really consider a fun or easy task. The English language is notorious for its complicated and sometimes even contradicting grammar rules. Use the best grammar that you know and if you are unsure, consult a grammar book like The Gregg Reference Manual or The Elements of Style. Once you have a draft of your document finalized, also feel free to email the documentation team mailing list and ask someone to review specifically for grammar details.
Textual Elements
When we talk about textual elements, we're talking about format, punctuation, and white space. (yes, white space)Since plone.org uses kupu as its editor, we suggest that you use all the provided styles in the drop down menu. This will make sure all your headings, etc. are all consistent.
Below are some other helpful hints on how to use text and white space to make your document more usable.
- Headings- Use pre-defined headings in kupu as appropriate.
- Text Justification- Text should normally be left justified with a ragged right edge.
- White
Space- Use white space to separate information so that readers can
easily identify section and to provide a frame for graphics.
- Abbreviations-
Use abbreviations sparingly. Spell out the acronym or abbreviation with
first time it is used in the text and follow in parenthesis with the
abbreviation.
- Bulleted list- Use the standard formatting
in kupu. Start each list with a stem sentence that introduces the list
in some way; use a colon at the end of the stem sentence.
- Numbers- Use the standard number function in kupu. Remember to number each step (action) in your document!
- Links- Use the standard formatting from kupu.
Attention Getters
Use these to help draw attention to certain things the reader should pay careful attention to.
| Item
|
Description
|
Format
|
|
|---|---|---|---|
| Result | | Use to indicate a response that the user should see. | Result: |
| Example | Use to highlight an example to further illustrate a step. | Example: | |
| Note
|
Use for content for which users should take special note.
|
Note: |
|
| Tip
|
Use for content that user may find helpful or nice to know, such as a shortcut or best practice.
|
Use the Call-out format from drop down |
|
| Caution |
Use for content that users should know to avoid minor frustration or inconvenience (like losing data).
|
Use the Pull-quote format from drop down |
|
| Warning |
Use for content that users should know to avoid serious, irreversible damage, or loss of data.
|
Use the Pull-quote format from drop down |
