I recently joined , 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. Jina AI 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 , , and Think Different Be What’s Next Disrupt your Docs! The tales of woe below are all true. I’ve personally experienced them…and worse. Note: 1. Sesquipedalian Loquaciousness Your team has put so much effort into developing its own jargon and slang. Sure, some may say it looks like or an explosion in a dictionary factory, but what do know? They wouldn’t appreciate your if it bit them on the proboscis. buzzword bingo they Sesquipedalian Loquaciousness Thanks to for the comic! SMBC 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 to want to use your code! bound 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? or ? Seriously though… projectname API 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 if you don’t have the freedom to write your docs in , Apple Pages, Microsoft Word, or . As long as you get the files onto GitHub it’s all good! Free Software Scrivener PowerPoint Some poncy coders use retro editors like Vim or Emacs. Me? I write docs in Lotus Word Pro 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 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… Seriously though… pain in the butt to open 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 , 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 LOL! have no ambiguity amazeballs acronyms Yes, that’s exactly what it means… 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? Seriously though… 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. 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. Seriously though… 5. If You Truly Loved Me, You’d Put the Work in… You don’t want just 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 (because those docs are , damnit). anyone convoluted password precious Obligatory XKCD comic 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. Seriously though… Think you can write docs that Jina is always looking for doc-stars and we’d ! don’t suck? love to hear from you

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

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Here’s Why I’m Gambling It All Away On My Open Source Startup

104 Stories To Learn About Go

105 Stories To Learn About Functional Programming

100+ Free Pluralsight Courses to learn Python, Java, and Spring Boot

10 Websites to Learn JavaScript for Beginners

104 Stories To Learn About Programming Top Story

Here’s Why I’m Gambling It All Away On My Open Source Startup

104 Stories To Learn About Go

105 Stories To Learn About Functional Programming

100+ Free Pluralsight Courses to learn Python, Java, and Spring Boot

10 Websites to Learn JavaScript for Beginners

104 Stories To Learn About Programming Top Story

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps