In this article
Write a draft of your article. Establish you page focus and be consistent with it. Revise your text for accuracy and length.
When you’re happy with your page pass it to a colleague for peer review. When sending it to translators ask them to share feedback or suggeestions.
Ask youself the following questions:
- Is the reader a prospective user, a new user, or an experienced user?
- What is the goal of the reader? To complete a task? To research a topic?
- Is the reader in the middle of a task? Is he/she in a hurry? Could he/she be frustrated?
Don’t overload a reader with unnecessary information, choices to make, or complex ideas or phrases, if you don’t have to.
Follow the guidelines outlined in the Writing Goals and Practical tips pages.
Here some other tips:
- Write a brief introduction of the page's focus, whenever possible.
- Stay relevant to the title - Don’t stray too far from the title or topic at hand. Use links to make related content available. If you find you’re getting too far from the intended topic, then you may need to create a separate but related article.
- Keep headlines and paragraphs short and scannable - most readers don't read the whole article but just scan it searching for the part that will answer their question. Keep titles short and descriptive
- Use the second-person (you) as if you were talking to the user
- Be as clear as possible. Use simple words. Avoid gerunds. Use short sentences and only few sentences in each paragraph.
- Provide context with embedded images or GIFs
- Use a positive text instead of a negative one. For example: YES: In order to buy bread you need to stay in line NO: If you don't stay in line you won't be able to buy bread.
Key tips for writing helpful texts
- Stay conversational, using contractions when appropriate.
- Avoid qualifiers that muddy meaning.
- Express understanding when appropriate.
- Craft clear transitions from section to section to orient the reader.