I’ve been spending a lot of time lately improving the documentation of my work so that newer employees can pick things up more easily. Unfortunately, my doc writing skills are garbage.
A lot of the guidance that shows up in technical writing guidance, is just plain good advice, so I’d recommend reading a book on writing. Here are two that I can recommend:
When Strunk and White advise the writer to use the Active Voice, they mean specifically, as Robert Day
puts it, to “not be afraid to name the agent of the action in a sentence, even when it is ‘I’
or ‘we’”. A good way to do this is to read your documentation out loud.
With regards to technical writing, don’t waffle: Tell the reader exactly what they need to know. If they can call one method or another, tell them how to choose. If they need to know anything to make the decision, tell them what they need to know as early as possible.
It’s also extremely helpful to have your documentation reviewed by as wide a pool of people as possible. It is easy to miss certain underlying assumptions or pieces of knowledge, and a small group of like-minded reviewers may not notice them either. The broader your group of editors is, the more likely you collectively are to notice and correct docs that rely on assumptions or background knowledge.
This was something I personally experienced in contributing to the Rust FAQ. This is a piece of documentation that is going to be read by people at a wide variety of skill levels, including those brand new to the Rust language, and those for whom English is not a first language. A lot of care had to be taken to avoid jargon, avoid colloquialisms, and be as clear as possible in word choice and phrasing. The level of quality we achieved would not have been possible without a wide array of contributors reading the work-in-progress document and pointing out the sorts of problems I described above.
I really should write a blog post about this, but some collected learnings:
Most importantly, go read good documentation. If you’ve never seen good documentation in the wild, you will have trouble writing good documentation–you want something with examples for “Oh, this is info the person reading will need”. Most docs for Web stuff nowadays is garbage. I’d look at:
Go read bad documentation. Here are some examples:
Identify your readers and what context they’ll have. Simply put, know what resources your readers will have when digesting your docs. Examples:
Hope that helps. I wish there was a way to get paid for these wounds. :(
One thing I’ll say about the MSDN documentation – there are some dangerously bad examples, or at least used to be. It was answering questions (about production code!) like “why the hell does this code sleep to change the seed of a random number generator?” that lead me to the belief that however much time you spend on your documentation, spend an order of magnitude more on the examples, including thinking about what will happen when someone decides to copy and paste them into their code.
My job is writing documentation.
The number one thing you can do to write good docs is have empathy for your users. I mean that in a literal sense: someone goes to your documentation because they have a specific need, and you are trying to provide for that need. In order to anticipate that need, you have to understand where they’re coming from. To me, this also means that you need to have contact with your users as much as you can; find out about them, what they’re trying to do, and what they think is hard. This is easier said than done, of course. You can also think of this in a “user role” kind of way: “A developer hears about my project, and wants to get started. They open the docs. What should they do?” “An experienced developer is trying to figure out how to use a feature. What do they do?”
This informs everything else you do, in various ways.
After that, “how do I improve my documentation?” is also a specific form of “how do I improve my writing?”. For me, the only way that I know of is to just do it, and do it a lot. And then get feedback, and do it some more. I’ve trained myself for years by arguing with strangers on the internet in comments sections (???), but it doesn’t have to be that. Just do it. It will be bad at first. You will get better if you keep doing it.
You might enjoy this talk I gave a while back. While it’s laying out my plans for Rust’s docs, it also works generally: https://air.mozilla.org/rust-meetup-december-2013/
I used to work on this at Twilio. Literally I would just grab people - anyone I could find who hadn’t used Twilio before and ask them to send a SMS to their phone, and watch where they got stuck. The key is you can’t say anything. But you’ll learn a lot from just watching people do that.
I gave a talk about this here: https://www.youtube.com/watch?v=sQP_hUNCrcE
Steve Losh’s article “Teach, Don’t Tell” has a good description of the different types of documentation and some documentation antipatterns to avoid, plus some writing tips.
In my mind I divide good documentation into roughly four parts:
The Black Triangle
In my mind I divide good documentation into roughly four parts:
Translations/summaries of the four parts:
First Contact = “what is this project?”
The Black Triangle = a “getting started” guide
The Hairball = in-depth guides on various parts of the system
The Reference = API docs, changelogs, etc.
A lot of the earlier Unixy docs had a major flaw.
No examples. No use cases.
Create illustrative (simple) examples, check them by actually compiling, linking and running'em.
You have a smart phone with a camera, use it. This gadget has to be wired this way round to that woojat… Take a pic and include it in the doc.
Explicitly and repeatedly encourage your new hires to “Click on the Edit” button. So they find a mistake, or an omission or find a useful link or whatever. Instruct them to “Click on the Edit Button” and make it Right. No, not “Add a comment”, edit it and make it Right. If they are not sure, tell them to edit it and make it what they think it should be and to ping you to check it.
Before you even think about documentation, make it as “Good as Possible” by Rusty Russell’s levels of Goodness for API design…
What the API levels are
10. It's impossible to get wrong.
9. The compiler/linker won't let you get it wrong.
8. The compiler will warn if you get it wrong.
7. The obvious use is (probably) the correct one.
6. The name tells you how to use it.
5. Do it right or it will always break at runtime.
4. Follow common convention and you'll get it right.
3. Read the documentation and you'll get it right.
2. Read the implementation and you'll get it right.
1. Read the correct mailing list thread and you'll get it right.
-1. Read the mailing list thread and you'll get it wrong.
-2. Read the implementation and you'll get it wrong.
-3. Read the documentation and you'll get it wrong.
-4. Follow common convention and you'll get it wrong.
-5. Do it right and it will sometimes break at runtime.
-6. The name tells you how not to use it.
-7. The obvious use is wrong.
-8. The compiler will warn if you get it right.
-9. The compiler/linker won't let you get it right.
-10. It's impossible to get right.
Note “Reading the Documentation” is down at number 2.
I would add before “Reading the Documentation” at 2.5…
2.5 Each unit test test case is readable executable documentation
of how it works.
Super clutch. Rustdoc does this and I don’t know how I lived without it before.
If I had to choose one thing it would be the Inverted Pyramid technique: https://en.m.wikipedia.org/wiki/Inverted_pyramid
Personally, internalizing that has made my docs and blogs much more effective.
Applied to writing library documentation:
This combined with writing separate documentation for separate audiences if there is more than one (developers, users, managers) has been most effective for me.
Code that is well written shouldn’t require much documentation. But that’s just my opinion. I usually write documentation on each class and method (for Java), and I write it in vim.
[Comment removed by author]
In my experience, and specially if this is the first time, get a technical writer to create the docs. They know the job and can help you to create a basic doc set that you can extend.
What does “well written” mean, and is its definition objective or subjective?
That argument seems to be often trotted out as an excuse for not writing documentation (although this may not be at all what you intended here), or for writing minimal or useless documentation. One of the things you learn when writing documentation for a broad audience is just how diverse people’s background knowledge is, and how many unstated assumptions often underlie both code and cursory explanations of that code.
While it is possible to overwhelm the reader with too much documentation, our profession seems to have a real problem with not enough documentation, and we probably don’t need to look for reasons not to write more.
I suppose it’s subjective, but general things such as good variable and method names are an example.
I agree that code should be easy to understand, which is what I think
you mean by “well written”, thus should not need extensive documentation
about how it does things. I often lament the lack of information
around why something is done [a particular way], which often you
cannot answer by just reading the code.
This is exactly what I meant, but I don’t think I was clear enough so my original comment came off in the wrong way.