1. 40

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.

Any suggestions?


  2. 14

    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.

    1. 11

      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.

    2. 21

      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:

      • The FreeImage docs are my gold standard for native library documentation. Note the pervasive use of examples and explanation, and the clear organization of where to find things.
      • The TGA format spec is my standard for file format documentation. Again, note the clear organization.
      • The MSDN reference pages are my standard for system API documentation. Notice the use of examples, notes, and most importantly, compatibility information. Man pages have nothing on Microsoft docs.
      • RFC3339 is a decent example of documenting the ‘why’ of a protocol. It’s a bit higher-level, but it does a good job of succinctly explaining why the authors chose to subset ISO8601.
      • The Github API is worth reading through if you are developing web stuff. In particular, note the assumptions and options and things they document for their HTTP work. It is a lot–often, you may want to say ‘This API uses the Github conventions for pagination and whatever else’.
      • The OpenBSD migration notes show really useful information for how to move between releases, including operations notes that can save a sysadmin’s ass.

      Go read bad documentation. Here are some examples:

      • The COLLADA 1.4 spec is a steaming pile of garbage, with internal errors. I’m not sure if its failure is on the part of the authors or on the part of the drooling idiots that came up with the file format, but it takes a long time to say little of value.
      • man mount is another great example of saying a lot without answering via example a simple question: “How the fuck do I mount a filesystem in one line?”.
      • The Confluence API somehow conveniently ignores everything involved in authenticating with Atlassian’s shitty software. This makes life difficult, and I hope they all get eaten by gigantic spiders in their native Australia.
      • Socket.IO shows the dangers of using examples as your primary means of communication. Additionally, for a language like JS, it is unforgivable to say “Oh, yeah, um, this function takes an object. What’s in that object? Um, key-value pairs?”. Fucking halfwits.

      Identify your readers and what context they’ll have. Simply put, know what resources your readers will have when digesting your docs. Examples:

      • Team members will (probably) have access to the source code, so you can omit implementation specifics at times.
      • External library users will not have access to the source code, so boundaries and public data structures need explicit documentation.
      • External service users need to know about overall performance guarantees and throttling, internal folks not as much.
      • Business folks need a high-level description of what it does so they can sell it.
      • Folks deploying your software don’t care how it works, but they need to know common failures and how to fix them.


      Hope that helps. I wish there was a way to get paid for these wounds. :(

      1. 3

        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.

      2. 10

        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/

        1. 7

          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

          1. 6

            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:

            1. First Contact
            2. The Black Triangle
            3. The Hairball
            4. The Reference

            Translations/summaries of the four parts:

            1. First Contact = “what is this project?”
            2. The Black Triangle = a “getting started” guide
            3. The Hairball = in-depth guides on various parts of the system
            4. The Reference = API docs, changelogs, etc.
            1. 5

              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.
              1. 4

                Create illustrative (simple) examples, check them by actually compiling, linking and running'em.

                Super clutch. Rustdoc does this and I don’t know how I lived without it before.

              2. 2

                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.

                1. 3

                  Applied to writing library documentation:

                  • “Most newsworthy info”: Changelog, tutorials/“recipes”, quickstart
                  • “Important details”: API reference
                  • “Background info”: History of the project, design docs

                  This combined with writing separate documentation for separate audiences if there is more than one (developers, users, managers) has been most effective for me.

                2. -1

                  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.

                  1. [Comment removed by author]

                    1. 2

                      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.

                    2. 3

                      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.

                      1. 3

                        I suppose it’s subjective, but general things such as good variable and method names are an example.

                      2. 3

                        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.

                        1. 1

                          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.