Friends Don't Let Friends Auto-generate Docs

Imagine you’re working with a new framework or library for your next project. You discovered the perfect tool. The README is perfect – not too much detail, not too little either. You’ve breezed through the installation and setup process, committed to using this new package, and suddenly you encounter a problem the README doesn’t cover. No problem, you’ll just head over to the official docs. What you find there makes you want to murder the original author. It’s auto-generated documentation. Friends don’t let friends generate docs.

Docs define a project’s culture and personality

At Aplo we don’t do auto-generated docs. Well, we do, but we don’t encourage new team members to read those docs. Those are just there for people who tend to prefer reading them. Your documentation, even if its just internal, defines your team’s culture, the project’s culture, and gives the software personality. These may sound like insignificant touchy feely things, especially to developers who are all about the facts, but they’re important for morale and they’ll likely determine whether your software slowly becomes a burden to your development teams or becomes a labor of love that everyone on the team loves maintaining.

I’ve worked for companies that use wikis and auto-generated docs to communicate information about a project to the rest of the team. Those companies sucked. Their software sucked. Their culture sucked. But the thing is, the road to suckiness was paved with each new disorganized, cold, sterile, half hearted wiki update. Don’t get me wrong, wikis can be a great source of knowledge for a project, especially when they live alongside the project itself like in GitHub or GitLab. They allow you to quickly document something that may not fit into the official docs and capture a time in the life of a project when a particular topic or set of topics was very relevant. But wikis just don’t have the heart that hand-crafted documentation does.

Auto-generated documentation is worse than useless. It gives you the impression that you’re doing someone a favor or actually documenting things but you’re not. You’re just showing people your code comments with some snippets embedded. Real code is about context. No auto-documentation tool can properly sort and organize your documentation in a way that would make sense for someone trying to dive into your project. These auto-doc tools are barely even good for deep-dive reference material because you can just look through the code for it anyway. It’s a real lazy solution. The only automatic document generation tool I think is half decent is Docco only because it doesn’t pretend to be something its not and it doesn’t burn my eyes.

A better way to generate documentation

Think about your project. Think about the types of people who will be reading it. Most of our documentation is for our own internal team members. Its all private and no one outside the company is allowed to view it but we still take the time to treat it like an open source project that we want to get attention for. Its part of building a culture of good, sustainable, quality fucking code.

There’s generally two types of people who will be reading the code. Those who need just the high level overview with examples so they can start digging in and those who already know the code well and need a deep dive. Normally people point out that tutorials are a third type but internally, so far, we’ve found that having a short tutorial mixed in with the general overview code is more than enough. If we were talking about a public project then I’d agree that tutorials are important.

That’s why at Aplo, while building AploQuote we’ve decided to write our docs from scratch. We’re designing a simple documentation site for every product and internal tool that’s a joy to look at, that’s fun, interesting, engaging, and has soul. Everyone on the team is responsible for writing new documentation and updating it. The docs are essentially a part of the product and something we’re proud of so we spend a lot of time on them. Some companies may scoff and say we’re wasting valuable time we could be using to fix bugs and build a better product but we know that the time we spend on this now will pay off when our software maintains a high level of quality and our company culture thrives while the guys using Confluence and all that old busted ugly Java shit will be falling apart, struggling to maintain morale and feeling more and more corporate every day even as the execs pump them full of more beer in a half-hearted, lame ass pathetic attempt to seem cool and startup-y.

Bottom line – take the time to really think about your docs. Organize them, write them well, design them with passion and you can’t fail. Your developers will thank you for it.

Software development, Web development

« We don't use CoffeeScript ever First five minutes on a new server »

Comments