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 firstname.lastname@example.org if you have any questions about how to use these. This resource list will also be available for download at http://www.heidiwaterhouse.com/docs-for-devs-workshop-resources/
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).
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?
An error message has three important elements:
- Unique ID
- Problem description
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.
The $thing is not working as expected because $reason.
Try rebooting the $thingservice and checking the status again.
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
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.
- What version it was fixed in
- What the symptom was
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.
- What version it was found in
- What the symptom is
- How you can mitigate, work around, or avoid it
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 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
- An overview of required steps
- Detailed steps
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.
- Install homebrew.
- Install javabeans.
- Install cowsay.
- Install cmatrix.
- Run the ourplace.py script.
Run the diditwork.py script to check that you have everything installed correctly.
(Bonus! It didn’t. Can you tell why?)
This is a partial list of resources that you may find useful after this workshop.
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
Everything recorded from Write the Docs.
Write the Docs Slack channel
I’d Rather Be Writing: http://idratherbewriting.com/
Hemingway Editor: http://www.hemingwayapp.com/
Pomodoro Technique: https://cirillocompany.de/pages/pomodoro-technique
Heroic Tech Writing: https://heroictechwriting.com/