Style guide for writing better copy

Everyone at some point needs to write copy (text): documentation, a proposal, or answers to support questions.

This topic provides guidelines on writing better, more effective copy. The guidelines are straightforward and can be applied anywhere.

Know your and your readers' objectives

For whom are you writing?

Start by having a clear view of your target audience. A developer will have a different background than an end user.

Guideline: split up the text and create specific targeted messages for different audiences.

A document about skins can be written from the point of view from a user, an admin and a developer. Your text will be better understandable if you have made this division, and create sections for each target group.

Determine your objectives: what do you want to achieve?

A document will have a goal: to inform or to set to action. Often it is both.

Guideline: do not try to mix goals. Separate the information part from the actionable part.

Informative text

You want the reader to learn something.

Guideline: briefly explain the text contents in context of the bigger picture. Also introduce the text by writing what the reader will learn, and what prior knowledge is required.

Write short and concise text: fewer words but well chosen. Add specific pointers where to find more information.

Actionable text

You want the reader to do something.

Guideline: write from the reader's point of view. Write down the readers' goals (not yours), and write how they will reach those goals.

An example of a reader goal is: "I want to improve the quality of my work". To convey this reader goal, a title for a page about writing documentation would not be: "Standards that should be followed by documentation developers", but: "How to write good documentation - standards and guidelines".

If the reader will go through a number of steps, for instance when registering, or writing a support question, you will help the reader by explaining what he/she can expect in the next steps. Instead of a button "[Submit]" we can write "[Continue] and write your question".

Provide examples. The more the merrier (as long as they are well organized), especially with screenshots. Well chosen examples build understanding.

Determine the readers' goals and needs

Determine the common goals and needs of your target audience. Note this also includes user experience-related goals, such as the following:

• "I don't want to feel lost"
• "I don't want to spend more time searching"
• "I want to feel connected to the writer/community"
• ... (please add)

Examples of rewritten copy

Note the rewritten text is not necessarily perfect and no blame is being attributed to the original authors; the examples are given just to provide insight on how the guidelines can be applied.

Example: Requesting access to Subversion

Before:

Have you read GettingStarted already ?

Please complete this form if you would like to Check In to the MAIN (Foswiki Core) or plugins Subversion repository.

After:

Before you obtain access to submit changes to Foswiki, we would like to know more about you: your background, your skillset, and what you would like to contribute.

The request process is as follows:

1. Fill in the form on this page. It creates a topic with a request to give you Subversion access to the Foswiki code.
2. After completing the form you can still edit the page — it is just a wiki page like all others.
3. Community members will provide their opinion in the topic.
4. In almost all cases you are granted access!

If you've read GettingStarted, please continue.

Example: Get live support

Before (example from TWiki Support homepage)

Ask questions, join the discussions on our #twiki IRC online chat channel (or use your favorite IRC chat application, see Codev.TWikiIRC for more info).

After (on our site):

Join our IRC chat channel #foswiki.

• No expertise required, just ask your questions!
• A lot of developers are available for your support questions.
• If you are new to IRC, read on at Internet Relay Chat.
• Get a taste of the conversations going on by browsing the logs.

Keep each portion of text cohesive

Each section of text should have a distinct purpose, both at a high level "(see Know your and your readers' objectives)" and at a lower level. When adding new information to a document, ensure each segment maintains its cohesiveness. Break down your topic into specific segments, each covering a specific aspect of your topic. Avoid discussing one aspect in multiple places, from the point of view of the set of objectives being addressed (in another document with different objectives, it may make sense to breakdown the topic in a different way).

Integrate your changes into the existing documents

Often you are tempted to dump a bit of new information somewhere in the Foswiki documentation suite, figuring that someone will eventually integrate your change into the rest of the document. Unfortunately, this can quickly reduce the cohesiveness of a document, or lead to documentation that repeats information in many different places.

Review the existing relevant documents and find the most appropriate section for your changes. Reorganize the documentation as required to ensure each section has a distinct purpose.

Use signposts to guide readers through a document

A long stretch of paragraphs with a similar typographical appearance can make it harder for readers to keep track of where they are, to quickly find a section of text that they read before, and to remember the purpose of the current portion of text. Various techniques can help provide guidance:

Use section headings. This is the most common technique and allows the table of contents to serve as a list of key signposts in the document. However, as keeping tracking of many nesting levels can be tricky, particularly due to the lack of automatic section numbering in widely-available web browsers, this technique has limitations with the current generation of web browsers.

Use inline headings. Start a paragraph with a highlighted sentence that describes the purpose for the current segment of text.

Make key phrases bold. This is a variant of using inline headings and is one of the techniques for making a document easier to skim. For some type of text, such as information hubs, this technique can be used effectively throughout the text to highlight the most important keywords and steps. For text that must be read at length, such as explanatory text, the technique should be used sparingly, only to provide navigational guidance to readers looking for a particular segment of text.

Use lists where appropriate. Note lists are for enumerating a sequence of items with a certain degree of coupling. Overusing lists is common and can lead to many nested levels of lists, so where possible, use a sequence of paragraphs instead, along with one of the other signpost techniques. In addition, due to its strict syntax, TML lists with items consisting of more than a simple paragraph are difficult to maintain.

Identify the text genre: information hub or explanatory text

Information hubs

An information hub consists mainly of pointers to other documents with additional information. Information hubs may contain some content as well, but typically this content will be skimmed by readers instead of read closely. Thus information hubs must be designed to be easily skimmed:

• Highlight key words and phrases. Emphasize them by using bold or italics.
• Group links into categories so readers can first locate an appropriate category, then a specific link within it. Even if the category is not explicitly stated, readers will be able to infer from the neighbouring links if they should continue to search that grouping for the desired information.
• Make links easy to browse through: typically this means putting them in list.

Explanatory text

Explanatory text consists of content that explains something that the reader must read in detail, such as a step-by-step procedure, or a detailed explanation of how a capability works. Due to the degree of attention that the reader must devote to properly understand the subject, it cannot be skimmed to learn the essential details. After having read the text thoroughly, however, readers need to be able to refer quickly to the specific section related to their current topic of interest:

• Use a signpost in each segment of text to prompt readers of the purpose of the segment.
• Keep each segment cohesive so readers can more easily find the information they are looking for.