Resources
This is a collection of templates and websites that may be useful to you as you go out and do your own writing. Feel free to contact me at h.waterhouse@gmail.com if you have any questions about how to use these. This resource list will also be available for download at https://heidiwaterhouse.com/docs-for-devs-workshop-resources/
Templates
Use these templates to make sure you’re answering all the questions that make documentation useful. You can add them to your work wiki or just pin them in your cube the way you do your Git command cheat sheet (don’t lie).
All documents
This is a general template for all documents that you’re going to write.
Why does this document need to exist? What is it explaining or answering?
___________________________________________________________
Who is the document for? Who will be reading this and what will they know?
____________________________________________________________
What is the answer to their question?
_____________________________
How do they know that their question has been answered?
_______________________________________________
Is there anything else they need to do?
_______________________________
Error message
An error message has three important elements:
- Unique ID
- Problem description
- Resolution
The ID should be something that is unique both in the external world (don’t use 404 for non-standard reasons) and as unique as possible within your system. Using one error ID for all your error messages makes it impossible for users to troubleshoot on their own.
Unique ID:
COMPANYPREFIX00000
Problem Description:
The $thing is not working as expected because $reason.
Problem Description:
Try rebooting the $thingservice and checking the status again.
Bug report
A bug report is written for an internal audience to describe what went wrong and help them understand the situation so they don’t have to come ask you about it. The ideal bug report means you never have to explain the bug again, you can just point to the write-up. Bug reports should have the following:
- What you were trying to do
- What you were doing
- What you expected
- What actually happened
- Any other information about what happened
Example:
I was logged into the $thrimble_module and I wanted to add an item to the YAML file.
I typed in $ – addition and clicked save.
I expected the file to save correctly.
Instead, the YAML file closed without warning.
I’m attaching a copy of the YAML file and a screenshot of the error message that did not appear.
Release note entry
Release note entries are usually a table of bugs that are fixed in this release. They’re like bug reports in a lot of ways, but because they are intended for an outside audience, they’re less casual and more focused on either how everything is better now or how to mitigate a known bug. It’s best practice to avoid blaming anyone for a bug – either the user or the software. This is a great place to practice your passive voice.
Fixed bug
- What version it was fixed in
- What the symptom was
- Status
Example:
In version 2.3, the Save button would run away from the cursor, preventing users from clicking it. That problem has been fixed and the Save button stays still.
Unfixed bug
- What version it was found in
- What the symptom is
- How you can mitigate, work around, or avoid it
- Status
Example:
In version 2.5, the Save button plays Celine Dion when users click it. Until this problem is patched, we suggest users use the CTRL+S command instead of the button. We expect to distribute a patch for this in version 2.6
Onboarding steps
Onboarding is a kind of technical writing that is frequently overlooked, but is very valuable for developers. It’s not just for people new to the company, but for anyone taking over a project or starting a new kind of process. A useful onboarding process makes our implicit assumptions explicit. This is the kind of document that’s very important to test. This section is only about the onboarding steps we use for software or computer processes. It’s also important to have onboarding for HR, bathroom location, and snack tube etiquette, but those are not covered here.
Onboarding steps should have the following:
- Basic skills you expect
- Pre-requisites
- An overview of required steps
- Detailed steps
- Testing
Example:
Expectations: These instructions assume you’re a system administrator with a basic understanding of installing packages on a *nix system.
Pre-requisites: Before you begin, be sure you have administrator access to the system you’re working on and a solid connection to the corporate network.
Overview: You’re going to download and install a bunch of hilariously-named packages, and then run a custom script to configure your environment for development at this company.
Instructions:
- Install homebrew.
- Install javabeans.
- Install cowsay.
- Install cmatrix.
- Run the ourplace.py script.
Test:
Run the diditwork.py script to check that you have everything installed correctly.
(Bonus! It didn’t. Can you tell why?)
Bibliography
This is a partial list of resources that you may find useful after this workshop.
Books
May I suggest a field trip to Powell’s?
Badass: Making Users Awesome – Kathy Sierra
Understanding Comics – Scott McCloud
Every Page is Page One – Mark Baker and Scott Abel
Modern Technical Writing – Andrew Etter
Read Me First! A Style Guide for the Technical Industry – Sun Microsystems
Microsoft Manual of Style – Microsoft
Responsible Communication Style Guide – Recompiler Magazine
Talks
Everything recorded from Write the Docs.
Websites
Write the Docs Slack channel
I’d Rather Be Writing: http://idratherbewriting.com/
hack.write(): http://hackwrite.com/
Hemingway Editor: http://www.hemingwayapp.com/
Pomodoro Technique: https://cirillocompany.de/pages/pomodoro-technique
Heroic Tech Writing: https://heroictechwriting.com/