Layman Explained: Reading documentation
Develop your documentation lingo
Ever read a sentence where you understood the individual words of the sentence perfectly, but not the sentence itself ? That’s what reading documentation feels like for most beginners.
And I don’t blame you.
When stack overflow’s answer ranks higher than Android’s official documentation, you know people are struggling.
Prerequisites
- Able to code in at least one language ( so you’re at least somewhat familiar with some of the terminologies used here)
- At least attempted to read a documentation or two before
What you’ll get out of this
- Able to better navigate through technical jargon.
- Understanding what terms should be understood differently depending on context.
- Nothing concrete per-se, but a better developed gut-feeling.
Putting on your reading glasses
A couple things to understand before we get started.
Documentation are for products
Every documentation out there is written by someone, or more likely a team, to describe a service/product that they have. They have zero obligation to write it in a way where it is thorough, nor up-to-date, nor easily understood, nor easily navigated, nor even 100% accurate. The more niched the product is, the smaller the community, the worse-off the documentation.
A human being wrote this
Someone had to make the decision, based on their intended audience, to maximize information delivered per word. There is always a fine balance between comprehension & information density.
Write too much, and veterans might fine it bloated and patronizing.
Write too little, and beginners would be overwhelmed.
More recipe guide than story book
Most of the time, documentation is meant to be referenced & leveraged, not read. If you know what you’re doing, you can read the guide non-chronologically, Ctrl+F to jump around, and still be able to get what you want out of it. On the other hand, if you don’t know what you’re doing, it’s easy to get lost in the weeds.
Tip 1: Understanding “Getting Started” vs “Docs”
Most documentation has 2 sections, written from 2 different perspectives.
- “Getting started” or “Quick start” or “Hello World Example” or “Guides”. This section usually contains small, simple, single examples of how to use the service. It contains a lot more “extra code”, and is meant to set the audience’s context right. Like a bicycle with training wheels — you might not go fast, but you won’t fall either. Comprehension is prioritized.
- “Docs” or “Documentation” or “Reference”. This section is like a dictionary or a phone-book. It’s more straight forward, and is meant for reference purposes. Information density is prioritized.
Here’s a couple examples
Example#1 Cloud Speech-to-Text from Google Cloud Platform (GCP)
Example#2 Moment.js
Example#3 Express.js
Express goes the extra mile.
- Getting started runs users through the most basic of functionalities
- Guide runs used through each functionality more in-depth, but with examples
- API reference is purely for reference only
Example#4 Android Developers Documentation
Tip 2: Types of interface
We’ll use GCP’s Speech-To-Text Quickstarts page as an example.
Q1 Why are there 3 types of quick starts ?
When a software/service/platform/app is created, the developers would have to make a decision on how to interface with their consumers. For example,
Spotify’s consumers would be the general public. Non technical, casual users. Hence, a mobile app, desktop app, and website is used.
Adobe Photoshop’s limiting factor would be the fact that it’s a resource-intensive tool. It takes a lot of computation power to get the most out of it. Hence, a desktop app and iPad app is used.
Back to our example, Speech-To-Text’s consumers would be other software developers who’ll be using this to build other apps and websites. Code literate, experienced, and have a decent foundational knowledge. Hence Google decided on using client library, CLI , and HTTP api.
Q2 What’s HTTP api, client library, and CLI ?
HTTP api. What is a HTTP api ?
Since most programming languages and frameworks support the usage of HTTP api, and is considered a “beginner” knowledge, the quick start uses curl in the command line as a generic example. It’s expected of you to know how to use curl, and implement it in the language of your choice. With this, you don’t have to install or import anything. You’ll be communicating across the internet with google’s servers to use the service.
CLI. What is CLI ?
Client Library. Sometimes called an SDK (Software Development Kit). Generally speaking, you’ll have a better experience using this as you’ll be shielded from all the fuss and mess of using HTTP api or CLI. It’s named that way because Google decided create and support a library for a handful of widely used programming languages (C#, Python, Nodejs etc).
Most service support all three types. Some do more, some do less, while some conditionally.
For example,
Example#1 Microsoft Azure Blob Storage
On top of the 3 mentioned above, Azure provides support for
- Web portal. Literally a website you can go to, click and drag and do whatever you want. Meant for casual usage for non-technical folks, but not to build a product out of.
- Desktop app. Same as Web portal, but instead of a website, is just a downloadable desktop app.
Azure’s HTTP api documentation is located in another page. There isn’t a “Getting Started” section of this. Only “Docs”.
Example#2 Amazon Web Services (AWS) Simple Storage Service (S3)
PS. AWS documentation is notorious to be difficult to work with. I personally am still struggling with it, to this day.
Example#3 Firebase
Firebase offers the standard client library and HTTP api.
The CLI designed to only do a specific type of tasks; Tasks where client library and HTTP api does not support.
Example#4 Slack Apps
Slack offers extendability by allowing for creation of mini applications on their platform.
Slack offers Client Library, HTTP api and HTTP api (events). No CLI is officially supported.
HTTP api (events) is HTTP api nonetheless, but it’s specifically designed such that it’s skewed towards the common use cases of a slack app. This makes the development much more convenient.
Example #5 Twitter API
Twitter supports client library (official and community) and HTTP api.
Community client library are libraries not officially created & supported by Twitter, but rather by the community who needed it so badly they took matters into their own hands, and built one for themselves. This is so widely adopted to the point where Twitter now officially endorses it.
Why is this important
Once you get the hang of the types of interface, you’ll be able to absorb a documentation more effectively. For example,
This is from Google Cloud Platform’s Cloud Vision API.
The guide uses only CLI to run the users through the steps. But now that you understand there’s client library & HTTP api, you’ll be able to convert these steps to the interface of your choice.
Tip3: Compilation of misc tips
The “$” sign
Generally speaking, whenever you see the symbol “$” in front of a line of code, it’s meant to run it in the terminal/command line.
File hierarchy representation
This is how file system hierarchy is usually presented in a documentation.
mysite is the parent folder with manage.py as a child file and another similarly named mysite as a child folder, etc.
When demonstrating how to use HTTP api
On top of curl, It’s common for documentation to use fetch as a generic example on how to implement HTTP api.
Demystifying common terminologies
Console
Usually used for services that are Platform as a Service (PAAS). Console is a website that you login into to manage all of the resources and services you’re using.
Client/Server
Client refers to the part of your code that your end users interface with. Synonyms: frontend, client-side
Server refers to the part of the code that your client interface with.
Synonyms: backend
Terminal/Powershell/CommandLine/CommandPrompt/Shell
Essentially this scary looking black box.
Terminal/CommandLine/Shell, if the context is unix-like operating system (Linux, MacOS)
CommandPrompt, if the context is Windows.
Powershell, essentially a more powerful version of CommandPrompt.
What’s next
Read more documentation.
Attempt to write documentation for your own projects.
Help others understand documentation.
Like my work ? Get my Hello World to Silicon Valley (a “just enough” approach to software engineering” at gumroad
