Github Documentation: a study on good technical writing for user documentation
In September 14, 2016, Github officially announced that the 4th version of their public API would ditch REST in favor of GraphQL. Alongside with this new API standard, a new user documentation was also launched to help developers navigate through this new world.
The current article analyzes the main characteristics of the Github's documentation that makes it excellent — and what we can learn from it.
Not all documentations are born equal
User documentation have the primary purpose of describing how a program or an API is used. User documents may come in a variety of ways, shapes or forms. However, there are three main types in which user documentation can be written:
Reference documentation
Garen Torikian, a former Technical Writer in Github, defines reference documentation as the one that defines the words and phrases that are unique to your product.[¹] For examples when describing a GraphQL API, these are your queries, mutations, types and similar. Broadly speaking, when you're documenting your API, these are your functions and methods that your user need to call to get access to your data.
Conceptual documentation
This type, on the other hand, describes how a system or parts of it works, what is used for and what it does. This may be in a more high-level, conceptual manner.
Procedural documentation
Also known as guides and tutorials. This type of document describes, usually, in an ordered manner how to accomplish something in a series of steps. These tend to concentrate less on in-depth info on how the program works and more on a hands-on guide.
'Rules' for a good and solid documentation
Good documentation is
- Trustworthy. Trustworthy means that you can trust the information available to you. You'll only be able to trust a user documentation if it is both accurate and consistent.
- Clear. Each user document must be clear about its purpose and do it well — or at least, well enough so it's capable of solving the user needs.
This means that writing only one type of documentation (as described in the last section) at a time is a safe bet. If you do otherwise, you might have a unique documentation that may be able to solve your user needs, but you'll probably end up with a sort of spaghetti documentation that does not solve the user problem.
What makes the Github's v4 doc so good?
The short answer it that it consistently follows the two rules of thumb described above. But that's not enough, let's dissect it a little more before proceeding.
Exhibit A:
Github separates between the different types of documentation:
Notice how there's a Reference tab where the reference documentation lives and the Guides tab, where the procedural documentation lives.
Exhibit B:
Each document serves one purpose and one purpose only:
Notice how this document serves one purpose and one purpose only. It is the reference to the acceptBusinessMemberInvitation mutation. It briefly describes its fields and response, but, there's no guide, no tutorial on how it works, when it should be used and related info
Exhibit C:
The reference is automatically generated from code. This adds a new layer of confidence of what's being changed in code is reflected in the reference doc.
"We wanted to generate documentation from our code." — https://githubengineering.com/the-github-graphql-api/
"The docs in the sidebar are generated from the GitHub GraphQL schema." — https://developer.github.com/v4/#about-the-graphql-schema-reference
Exhibit D:
Last, but not least, the UI is just really good. Really simple to navigate, to find what you need and overall, just good aesthetics.
What can we do
You don't need to be a successful business like Github to be able to write a solid documentation for your product, but surely we can learn a few things from Github great doc.
Automatically built reference
This seems to be a no-brainer. If there's something that a computer can do well enough, why waste developer time in this? Specially in a repetitive and boring task. Just automate it.
Automatically generating the reference documentation also makes it easier to keep the documentation up to date with the code, as they are so close. Your team can also use linters and code reviews to block undocumented fields.
Strong procedural reference
But probably, just a computer generated reference won't be enough for your clients to use your product. If that's the case, guides and tutorials may bridge this gap and help your clients navigate and use your product.
And, as your team moves towards automatically generated reference, more time will be freed to work on more quality guides and useful tutorials.
Reference
[1] — Garen Torikian talk Write the Docs Prague 2017. This talk is really good. If you are interested in this topic, I highly suggest you go see this.
Author notes
I am by not means a technical writer. This article is an opinionated article by a software engineer on what, well, makes a good documentation. Feel free to make a response in the comments section, I'd love to read other people's take on this matter.
If you liked this article, please leave a ❤ down below!
