7 steps for technical writing
- Define your audience and scope
- Plan
- Research and write
- Test, review, and revise
- Deliver
- Evaluate and get feedback
- Revise, archive, or remove
Define your audience and scope
This is the who, what, and why: Who are you writing for, what do they need to know, and why do they need to know it.
Choose a persona - this can often be a real-life person representative of your audience. "Representative" is the key phrase here: Write for the rule, not the exceptions.
- What do they already know?
- What do they need to know and why?
- What is the real-life context, where and when will they need to know it?
Plan
Define the how, where, and when.
- Where is the best place to put this information? Think about where your persona will need it and where they'll be most likely to find it.
- When does it need to go live? Plan out your timeline.
- Who do you need to get involved to help you or to consult with?
- How are you going to test and review it, and make sure you get the feedback you need?
- Will you need video or graphics? How are you going to create those?
Research and write
Consult with other experts, spend time with the interface, and do the research you need to make sure your documentation is accurate and meets the needs of your persona.
- Define the information your persona needs to know using a task-based approach.
- Map out steps into smaller, achievable parts.
- Think of each part as a block you can move around - it should make sense on its own.
- Assume people will skip over parts and skim.
- Don't assume anything about your persona.
- If you assume things they don't know, they will be lost.
- If you talk down to them, they will be offended and won't use what you create.
- Define jargon and acronyms.
- Be clear and precise.
- Use active voice.
- Avoid long paragraphs and dense blocks of text.
- Only use graphics that support learning - don't use irrelevant decorations.
- Check your capitalization, punctuation, and style - consistent formatting and terms helps with clarity.
- Edit and then edit some more - most documentation is better if it is shorter.
Test, review, and revise
Always have someone edit your documentation. You may want to have multiple editors, one for style and one for content. Whoever it is, make sure they feel comfortable critiquing you and that you don't let your ego get in the way.
When you are the one editing, look for:
- Accuracy
- Are the steps and information correct?
- Does it meet style guide standards?
- Simplicity
- What can be cut?
- Is there passive voice, jargon, or acronyms?
- Is there information that lives elsewhere that could just be linked to?
- Effectiveness
- Does this do its job?
- Is it super boring or hard to read? How can you make this more digestible.
Deliver
Make your new documentation live to the membership. To do this:
- Publish and check permissions - make sure the people who need to access it can.
- If it is a new page on a website, make sure it has a place in the menu structure.
- Share your work through the appropriate channels: email lists, the SWAN Community Forums, user group meetings, etc.
Evaluate and get feedback
Once your documentation is in the real world, you will find out if it is working or not.
Monitor statistics and use - very low use might be a sign your documentation should be moved to another location or that it is not valuable to your audience.
Be prepared to make changes based on feedback from your audience, whether that is library directors, patrons, or another group.
Revise or remove
Documentation often has a limited lifespan - hardware, software, and websites change regularly, we add and remove services. Documentation takes more maintenance effort than other types of content, so be prepared to manage it through it's full lifetime.
To help with this process, the UX team leads a yearly content audit.