Advertising sustains the DA. Ads are hidden for members. Join today

On this page

2.2. Writing Good Documentation

Last updated on
11 January 2024

Follow these guidelines when writing topics for the User Guide.

On this page:

2.2.1. Speak to the audience

The intended audience for the User Guide is site builders with general web knowledge but no specific knowledge of Drupal. Make sure your writing is appropriate for this audience.

In terms of the Drupal community personas, the goal of the User Guide is to help Learners make a successful transition to Skilled.

2.2.2. Keep it concise

A good guideline to follow when writing documentation is to keep the writing to a minimum. Include just enough information so that the information is conveyed.

2.2.3. Convey information in text and images

Keep in mind that not all users of the User Guide can see images. Therefore, we need to make sure that all of the information is conveyed in text, independent of images.

At the same time, many people learn best through images. So, especially for task topics, we want to include screen shots, especially for web forms. These would typically include:

  • A screen shot of a form that will be filled out. For the mechanics of including images in your topic, see Section 1.2.7, “Including images and videos”.

  • A table of fields and values to fill in. Sample table code (this example is for creating a menu link): 

    [width="100%",frame="topbot",options="header"]
|================================
|Field name|Explanation|Example value
|Menu link title|Title to be displayed in the menu|Opening hours

(rest of the fields go here)

|================================

Also, the last step in a task topic would typically be something that shows them they succeeded (like viewing the content if the task is to create the content), with a screen shot of what it looks like. For the mechanics of including images in your topic, see Section 1.2.7, “Including images and videos”.

2.2.4. Describe reactions to actions

After describing an action for the reader to take, like "Click Submit" or a navigation action, describe the site’s reaction. Examples:

You are returned to the Content page, with the message "Your content has been
updated" at the top.

The Content page appears, with a list of the content on your site.

A screenshot is also appropriate, in most cases. This mention and/or screen shot can be omitted if the reaction is either very obvious or repeated. It can also be combined with the next instruction, such as in this Views example:

Choose Rearrange from the dropdown button in the Fields section. In the
Rearrange pop-up dialog, ...

2.2.5. Focus on skills and knowledge

The objective of the User Guide is to be a learning tool and documentation, not a recipe. It is also not supposed to be marketing. So although the guide may contain instructions for specific tasks, those may not be the exact tasks that a reader will eventually need to perform. Keep this in mind as you write task topics:

  • Think about the skills that someone would need, in order to be able to do similar tasks, rather than focusing on a narrowly-defined task.
  • When describing the goal and writing the steps for a task topic, make it concrete by using the scenario as an example (see Section 2.3, “Following the Scenario”), but at the same time make it clear that this is an example (use phrases like "For example").
  • In the Expand your understanding section (from the Task topic template), list related tasks that someone who has just read your task topic should be able to perform, and that might lead them to solidify and broaden their skills and knowledge.
  • Provide information, not enthusiasm.
  • Avoid jargon, jokes, and slang.

2.2.6. Encourage best practices

Make sure that all topics encourage best practices. Considerations to keep in mind:

Attributions

Written/edited by Jennifer Hodgdon and Joe Shindelar.

 

This page is generated from AsciiDoc source from the User Guide. To propose a change, edit the source and attach the file to a new issue in the User Guide project.

Source file: good-writing.asciidoc

Help improve this page

Page status: No known problems

You can: