No Docs, No Software

September 24, 2024

Let's poll your favorite softwares

Think of all of the software you have directly used in your life. If you're a developer, think of all of the software you've integrated with (libs, apps, APIs, etc). Now, reduce that list of softwares to only those that you loved or that helped you non-trivially.

Count how many of those helpful softwares had supporting documentation. I'll put money down that it was nearly 100% of them, wasn't it?

Let's consider the inverse. How many genuinely helpful softwares have you used that came with no documentation? Probably none, right?

Why is it, then, that our developer communities write so little internal documentation?

Speaking from experience, internal documentation represents one of my greatest successes, and also one of my greatest failures. Here it is:

Monorepo documentation file contributors. (e.g. docs/**/*.md)

Sorry, you may have to zoom a little to see the above clearly. No, I promise I'm not trying to show off. No, I'm not looking for a pat on the back. I'm demonstrating my commitment to the belief that if you haven't written down how to use your software, it may as well not exist.

Do you see where my failure was? If not clear already, my failure is that the chart above is nowhere near uniformly distributed. What I can observe from this data (generated with a lil' git scripting), is there are about a dozen power writers out of 1000+ developers. This was a big codebase! ~1 writer per 100 developers is not great at all. Were those other 99 developers not writing libraries or APIs? Spoiler: they absolutely were. Spreading the "gospel of documentation" and flattening that chart would equate to greater success for me.

If you're selling cars, fuel must also be available. Software is the vehicle, and documentation is the fuel that your customers burn through to accelerate the software into motion. Users are only going to use that software if:

1. you give them resources for success (docs!), or
2. they're forced to use it, or
3. they have exceptional motivation to get your software to work. This generally only occurs if your software is rare and critical to the user.

If you're writing the software for others, why wouldn't you want to help your users?

Monorepo contributor documentation file word count. (e.g. docs/**/*.md)

> but but but!!!

Here's some top tier malarkey against writing docs.

"the code is the best documentation!"

We've all worked worked with engineers who say "the code is the best documentation".

These people are naive, and forget who code is for.

Humans--mortals--speak their mother tongue. Code, no matter our expertise, is our second language. Further, it is indirect, and forces the reader into non-linear reading (aka jumping, tracing, etc around the document).

Not my code, sir! It's fluent!

Sure, kid. You can use your pipeline operators, fluent methods, monadic or let-style tricks--the above claims hold.

In all fairness, this mantra does hold for small projects, especially those with itty-bitty interfaces where the interface and typing alone expresses crystal clear semantics.

This all falls apart rapidly when dealing with systems of software, or even small softwares with configurable options. If you are using other's software, you are likely using it such that you can leverage some canned value. Reverse engineering software to exploit its canned value can negate that value, or minimally, diminish it, as that value is no longer canned--you had to open the can and stir it just to consume it!

"internal documentation isn't as important that external documentation!"

Absolutely! Does that somehow negate the fact that your internal software needs to be used/consumed/read/deployed by your peers? Of course not! Lesser importance does not negate the need to write docs.

"I'm getting paid either way"

No one has actually said this to me :). Regardless, documentation seems to rarely be formalized or normalized into software teams' default rhythms. I know there are exceptions to this--super cool teams are out there. I've worked with literally hundreds at a global corp and more in smaller firms. I just don't see it.

"My software is a GUI, and that GUI makes its usage self evident"

Customers using the GUI is not the customer to which I'm referring. Customers--including your peers--whom have to consume, say, components/widgets/utilities in that codebase are the users to which I'm referring.

Is it really worth it?

Yes. Here's why.

• Docs help your users. Don't force your users to go spelunking into code. Give them what they need, at least for the 80-90% of use cases. It may be ok to send the power users spelunking--use your best judgement.
• Docs are cheap. Docs often take seconds-to-minutes to write. If someone says "ahhh that's too much work" they are not being honest. Docs don't have to be long or exhuastive. In fact, concisely covering the how/what/why/when to use your software, accompanied by a minimal example or two, may be the best outcome!
• Docs will improve your design - robustness. If you have to define the behavior of your system in text, you will often exercise your system literally or virtually, and thus periodically identify edge cases that may be filled.
• Docs will improve your design - UX. Docs are your artifact's public image. You want your software to be delightful to use. It's often the case that docs (and often equally tests), give you a chance to exercise your work just as your customer would. This helps you constrain and refine your interfaces to make them human friendly.

Conclusion

Write docs, man!