Task based Articles Recipes

When writing a guide or article about how to perform a specific task, here are some tips to speed up writing time and improve the quality of the finished article.

Preparing to write

Some questions to help you identify the key information to highlight:

• What pain points does this task address? Who would be interested in learning this information?

• If I was a developer trying to find this article, what keywords would I be using to search for it?

  • Are those keywords highlighted early in the article?

• Is there a real-world problem or user story around which you can frame the article?

• What are the key points they need to know? E.g. They must use the X operator with parameters a,b, and c.

Before you Start Writing

If the article has a long list of instructions, put together a table of contents first to organize the flow of the instructions.

Examples:

• https://developer.ibm.com/streamsdev/docs/streams-quick-start-guide/
• https://developer.ibm.com/streamsdev/2018/01/12/calculate-moving-averages-real-time-data-streams-designer/
• https://developer.ibm.com/streamsdev/docs/common-patterns-tracking-moving-objects-streams-part-2-geofencing/

You can create links to sections in the doc using the anchor tag, e.g:

- [step 1](#step1)
- [step 2](#step2)
...
<a id="step1">
<h2>Step 1</h2>

The section below outlines things that you should cover, but your outline and table of contents are important to flush out first.

Sample outline

Introduction

• A brief summary of what this article is about and what we are trying to achieve. If there is a pain point or problem that the article solves, mention this and show how the task you are describing helps to solve it. If there is another tool or way to do this, explain why they would use this option and not the other.

Skill Level

• Expected skills level - what does the reader need to know to understand this article?
• If the user does not have the required skills, where should they go to learn more?

Requirements/Information to collect

• Any software to install? Where do they get the software? Which version?
• What toolkits do they need? Where do they get the toolkit? How to set it up?

Discuss any information to collect:

• E.g. If the user is connecting to Event Streams in IBM Cloud, what credentials info they need to collect and how to collect it?

Steps

• Outline major steps to complete the task, e.g. They must use the X operator with parameters a,b, and c. State that early and repeat it a couple of times.
• Discuss details about each step
  • Keep the steps to the point and concise.
  • Make sure there is validation at the end of each step ... so the user knows that they have completed the steps successfully. i.e. what should the user see at the end of each major step?

Avoid discussing information that is interesting/cool but that a user, especially a novice, does not need to know to complete the task.

Additional Resources / What's Next?

• List of resources to help the user learn more about the task?
• What can they do next?