Photo by Kaleidico on Unsplash
Your software will thrive or die because of its technical documentation.
Think about it.
If developers can’t figure out how to use your software and use it quickly, they won’t adopt it.
It’s that simple.
“The palest ink is better than the most capricious memory.”
Arthur H.Smith
This isn’t a new trend, and it applies to all software. Not just the “things” hidden away on workplace servers, chucked together in 1995, and only for use in one oddly specific situation.
GitHub’s 2017 Open Source Survey highlighted that “documentation is highly valued, frequently overlooked”.
Two years later, the 2019 HackerRank Developer Skills Report, then showed us that 74% of Junior Developers and 55% of Senior Developers, thought their number 1 pet peeve at work was badly written documentation.
Postman’s 2019 State of API Survey also found in the same year, that over half of their respondents felt that API documentation was “below average or not well documented”.
Then finally, this year, CodingSans’’ 2020 Developer Survey highlighted that, for developers “the main challenge is sharing knowledge, which is the same as last year”.
The proof keeps on coming, no matter whether the documentation is for internal-facing software, open-source software, API’s or anything else — it’s an area where many fail.
What makes documentation excellent though, and how do you create it?
Your goal should be to provide viewers with whatever information they need, to get to the right answer, solution, or resources, as quickly as possible.
The biggest challenges you’ll face to this are keeping your documentation up-to-date, accessible and visually appealing.
Even though each piece of software is unique, and might require, or be better suited to certain elements, here are some best practices you can follow no matter what.
- Comprehensive: Your documentation must cover every aspect of your software, without making any assumptions about the viewer’s knowledge.
- Up-to-date: Nothing will be more frustrating to a viewer, than putting them in a position where they think they’ve found the right answer, only to realise that the information is out of date. Your documentation has to stay up-to-date, or it’s useless.
- Easy to Find: The faster a viewer can find what they need, the happier they’ll be. A well-constructed menu, comprehensive search functionality and links to related resources, will all make it easier for viewers to find answers.
- Visually Appealing: Recent research from TechSmith has shown that people absorb visual information faster, and perform tasks better when instructions are presented via visual or video content. Use these to show-off how your software works.
So, you’re convinced. Good!
There’s a new problem though. You know you need documentation, and you need it fast, but you’re staring at a blank page and not sure where to start.
Don’t worry — here’s some inspiration to push you in the right direction.
Stripe
Stripe is a popular payment gateway that allows individuals and businesses to accept payments over the internet.
Their API documentation ticks all the boxes — it’s comprehensive, up-to-date, easy to find and visually appealing. When it comes to the final point, their usage of example syntax is best-in-class.
Heroku Dev Center
Heroku, in their own words, “is a platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud.”
The Heroku Dev Center has plenty of bases to cover, given all the supported languages, but it does a great job at funnelling viewers in the right direction straight away.
Once you’re on the right path, you’ve then got access to plenty of tutorials, practical syntax examples, and further resources to help you carry on further.
MailChimp
As our final example, MailChimp is an email service provider that allows you to create, manage and send email newsletters.
It’s immediately apparent how much effort has gone into the look and feel of their documentation. The structure of information between guides and references is also well-considered and caters to a full range of abilities.
Simply put, proper documentation can be the difference between someone having a great experience with your software, and a terrible one. It’s no longer optional. To developers, it’s the ultimate good or bad marketing, and it instantly shows how much you care.
It’s not just for those discovering your software for the first time either. Returning developers might want to refresh their memories, or could be looking for a solution to an issue they’ve encountered.
Either way, if you want people to shout to the hills and back about how much they love your work, providing excellent documentation is essential.