How to [name of task]
Task-based guidance helps users complete the most common integration tasks, based on the user needs from your research. Most of your documentation should be in this format.
Good examples include:
- Refund a payment - using a REST API
- Deploying apps - using a native API
Your team’s developer, user researcher and technical writer should work together to identify the most common tasks your developer users need to complete.
Each task-based guidance section should:
- help users complete one task
- have a front-loaded title that starts with a verb
- include example code for a request and response
- include descriptions for the request parameters and response fields that relate specifically to the task
- avoid duplicating basic information about the API - link to your ‘Get started’ section instead
- link to any tasks that users need to complete afterwards
Task-based guidance should be more detailed than just a description of an endpoint and method. You should guide users through the task by:
- talking directly to your user - use ‘you’ and active verbs
- using the active voice and plain language
- describing the task not the technology - tell your users what they need to do, instead of describing how the system works
- using numbered steps wherever you can
Keep task-based guidance concise. Do not include every possible request or list complete API responses. You can link to your API reference for users who need more detail.
For each task, you should tell users what to do if they have a particular need - for example a common alternate request, they get an error, or something goes wrong in the API flow. Add a front-loaded heading and section for each need. Include these on a page with the task - do not create ‘troubleshooting’ or ‘FAQ’ pages.