How to write (terrible) documentation
Hey, hey software developer! You just finished writing some badass code for a new product or tool that everyone is going to want to use, right? Now, time for the easy part — write some docs to help all your new users onboard with your project, you rockstar, you.
These handy tips will ensure that even the most well thought out products will be completely unapproachable to the average user. Because, who wants to attract average users.
Step 0— Make assumptions about your user’s knowledge base
You’re a 10X rockstar, unicorn, guru developer with 20+ years experience in your field and 2 PhD’s, yes? Cool, cool; assume everyone else has these same credentials when writing your technical docs. Throw in unnecessary theoretical math and refer obscurely to Satoshi Nakamoto’s white paper for no apparent reason.
Step 1— Don’t include code samples or use cases for your product
Look, the user should be able to figure out how to utilize your tool in their code base just through instinct. Don’t worry about explaining required parameters for functions or providing sample code that shows how to achieve desired results. Let error messages be the user’s guide — they’ll figure it out eventually.
Step 2— Use technical jargon when plain English would suffice
Does your software use someone else’s server? Nope — it’s serverless. Is your software hosted on someone else’s network of computers? Nope — it’s cloud-based. Did you write a snippet of code that performs a repeatable function? Hell nah — that’s a proprietary algorithm. Oh, also, if you use an obscure technical term, definitely don’t define it or explain it. That’s what Google is for.
How are you ever going to get funding if you don’t confuse the shit out of your users and potential investors to get them to blindly throw money at you, right?
Step 3—Repeatedly redirect users to other pages within your docs
Ideally, don’t actually explain or define anything until the user is, like, 10 clicks deep into your documentation. Even better, once the user gets about 15 clicks in, redirect them back to the home page of your project docs. Brilliant.
Step 4 — Leave out critical details from your setup process
Does your user need to follow specific protocols to be able to use your product? Of course they do — but don’t tell them that. They should just know. If your user needs to install specific versions of dependencies to use your tool, they can figure that out on their own. Leave out a dependency or two, just for shits and giggles. In the long run, your user will gain valuable debugging skills from trying to figure out how to get your epic product up and running.
Step 5— Use unreadable fonts and colors, and HTML templates that look like they’re fresh out of 1998
Ideally, when users get to your docs page, you want their face to look like this:
Because you don’t want to give anyone the impression that you care about appearance or front-end development or UI/UX design. Is front-end development even real engineering? Lol, of course not! So why waste your time making your docs readable and accessible? All your power users are just going to use the man pages in their terminals anyway, and they’re really the only ones who matter.
Well, there you have it. A foolproof guide to writing god-awful, mind boggling documentation and alienating your users. If all else fails, just create a splash page that perpetually says your documentation and support are “coming soon”.
This satire is based on experiences I have had reading extremely confusing and/or non-existent documentation. My intention in writing this is not so much to poke fun at bad documentation, as it is to point out how important, and how difficult it is to write clear, easy to follow, documentation. Want to hire an engineer who also writes solid docs? What luck! I’m on the market, we should talk.
