Skip to content

Task based Articles Recipes

Jump to bottom Edit New page
natashadsilva edited this page Jul 30, 2020 · 3 revisions

When writing a guide or article about how to perform a specific task, it is essential to do a bit of planning before you actually start writing. This will 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.

Once you have these key ideas clearly in mind, create an outline/table of contents. This helps you organize the flow of the article and makes sure it is logical.

Before you Start Writing

Writing the table of contents was probably the hardest part of the writing process, but it was (now that I look back) the most important part. I knew what I wanted to cover in the book (in a very general sense), but I didn't know exactly how and where each topic would fit. -- Susan J. Fowler, How I wrote my first technical book.

The point is, knowing what you will write and how it should flow is the first step to useful, easy to follow content.

So please, put together a table of contents first. It is an indispensable way to organize your thoughts and make the writing process seamless.

Examples:

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

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

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

Information to collect

Discuss any information to collect

  • For example, if the user is connecting to IBM Cloud, what credentials info they need to collect and how to collect it?
  • For Kafka, what information they need from Kafka configuration 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?
Add a custom footer
Add a custom sidebar
Clone this wiki locally