A Plea to Developers Everywhere: Read Your Own Docs

If you can't go through your own documentation and produce the exact result you want other readers to, you haven't read your documentation.

I've been doing some developer hiring and recruiting lately, and part of my process is a coding exercise. But it's not a coding exercise. It's an exercise in:

  1. Can you read and execute on a set of discrete directions?
  2. Can you write documentation?

I don't think that when hiring a software developer there are any two more important skillsets when it comes to delivery execution. Yes, being a "good" software developer includes being able to code and communicate well with colleagues, but these are derivative of being able to understand and execute on a set of directions or leaving directions behind for the next person to continue your work.

It is clear though that while following directions is a lost skill for most, writing documentation is just as abandoned a craft. And it really comes down to one thing that every developer needs to do: when you finish writing your docs, go through the steps you documented yourself and ensure that you end up at the place anyone else reading them would.

Do Not Make Assumptions

One of the biggest gaps in docs I get from developers clearly comes from the developer making assumptions, usually discovered when you see:

  • An environment variable needs to be set for something to work, but the docs never mention it. Presumably when the code fails to execute, I'm supposed to debug it and find that a step is missing in the docs that says "Set XYZ to 123"
  • I need to be in a specific folder in the code base for a command to work. You told me to run `npm i` in the README, but didn't tell me to `cd frontend` first. Sure, I'm smart and can figure that out - but if you don't tell me to add flour to the bread, all I'll have is water and yeast
  • I need to build a Docker image, but you didn't tell me that I needed to set a build arg so that a layer in the image could go fetch dependencies from a private NuGet repo

Etcetera. Do not make assumptions that your reader can just figure out your missing steps.

Provide Specific Code Samples

The other thing that ends up wasting increments of time that eventually add up is not including code snippets (command line code, helper scripts, etc.) that are not part of a build script included in your code, but are needed to get the code to run. For example:

  • Instead of telling me to "install dependencies" - tell me to run `nuget restore` or `pip install`. Put the command right in the docs.
  • Instead of saying "create a .env" file, provide an example env file, with all of the required environment variables
  • If I need to seed a database or provide input data, provide a sample of what that data needs to look like

Not providing samples of code or data just creates more guesswork for the person trying to run your code, which in turn - wastes time. I have seen some code exercise submissions where the candidate is clearly a talented software developer. But when their documentation is poor, it means that on a team of many developers they risk insulating themselves with knowledge and not promoting the productivity of the team as a whole.

To get better at writing docs, start by reading them.

Ryan Norris Ryan Norris

Ryan is the former Chief Product Officer at Medullan, CTO at Be the Partner, and CTO and General Manager at Vitals. He currently works as a fractional CTO offering strategy as a service to growth-stage companies in health care and education.

Recommended Posts