How to Lose Developers and Alienate Users: 5 Ways Not to Write Docs

I recently joined Jina AI, a startup focusing on neural search. One of the things that got me interested was their documentation — while not perfect, it’s straightforward, practical and easy-to-read. I wish that were just as true of every tech product out there.

I wrote the following quite a while ago, but I think the lessons still apply…

You know, there are so many projects out there with great documentation. But you’re not like those other girls. You do things your own way.

To make your docs stand out, why not make them crappy instead? Just think of the buzz you’ll get on Twitter and all the questions on Stack Overflow trying to find out what anything means! And who needs GitHub Stars when you have an issue queue overflowing with basic questions?

So, without further ado, let’s Think Different, Be What’s Next, and Disrupt your Docs!

Note: The tales of woe below are all true. I’ve personally experienced them…and worse.

1. Sesquipedalian Loquaciousness

Your team has put so much effort into developing its own jargon and slang. Sure, some may say it looks like buzzword bingo or an explosion in a dictionary factory, but what do they know? They wouldn’t appreciate your Sesquipedalian Loquaciousness if it bit them on the proboscis.

Thanks to SMBC for the comic!

Your long words and purple prose ensure everyone can see how smart you and your development team are, and with such an intelligent (and I’m sure physically attractive) team they’re bound to want to use your code!

Seriously though… Not all of the folks reading (or contributing to) your docs will be native speakers of your language, and not even native speakers may be able to understand how you’ve strung words together willy-nilly. Also, seriously, what are people more likely to Google? projectname API or projectname metasynergy protocol?

2. Mark Down? Who He?

Everyone should be free to use the authoring tool of their choice. After all, what’s the point in Free Software if you don’t have the freedom to write your docs in Scrivener, Apple Pages, Microsoft Word, or PowerPoint. As long as you get the files onto GitHub it’s all good!

Some poncy coders use retro editors like Vim or Emacs. Me? I write docs in Lotus Word Pro

Seriously though… I’ve had to deal with Apple Pages files being uploaded to repo’s before, and that was by members of the internal dev team by chrissakes. They’re a real pain in the butt to open using a Linux box, and how on Earth are you going to do version control on those things? That’s not to mention the time a junior dev uploaded Markdown pasted into a Word file, which they then renamed with an .md extension…

3. Yeet those 🗎 and smash that “Clone or download” button, fam 😎

Your project is cutting edge, so your docs should reflect that. No need for any of that frumpy old English — Emojis work across languages and have no ambiguity, and if you want to attract a cool, hepcat group of rockstar ninja hackers you need to speak their language. Not employing any 13 year olds? Just ask your niece to yeet something up for you! And don’t forget those amazeballs acronyms LOL!

Yes, that’s exactly what it means…

Seriously though… It’s fine to have some emoji’s to break up the document and draw the reader’s eye, don’t use a scattershot approach. Use them to add context, not replace content — after all, if a developer is reading your docs in a terminal, who knows how those emoji will render?

And trying to be cool with your slang? Please, just don’t. Nobody hits up developer docs to be entertained. And again, many of your readers may not be native English speakers or born in your generation.

4. A Thousand Eyes Make All Docs Perfect

Your docs are the lifeblood for your ecosystem of developers. And nobody wants dirty blood, do they? Best to have your team of experts check everything three or four times before uploading, and then get final approval from the CEO before pushing to master. Users won’t mind waiting a few weeks (or months) for a basic API reference as long as every T is crossed and every I dotted.

Seriously though… The perfect is the enemy of the good, and there are a lot of amazing projects out there catching the eyes of developers. Release early, and release often. It’s better to have some basic docs out there that do the job, rather than a perfect all-singing, all-dancing ensemble that’s already out-of-date by the time its released.

5. If You Truly Loved Me, You’d Put the Work in…

You don’t want just anyone contributing to your project or using your tools. Only the best are good enough — and your application and vetting process ensures that only the crème de la crème will get that coveted repo access…any day now. Be sure to ask them for their LinkedIn profile (so you can see they’re a true professional), their phone number (because data leaks and phishing aren’t a thing), and a convoluted password (because those docs are precious, damnit).

Obligatory XKCD comic

Seriously though… Developers are typically looking at several options to get the job done, and adding friction will just push them elsewhere, regardless of how great your project is.

Think you can write docs that don’t suck? Jina is always looking for doc-stars and we’d love to hear from you!