How to find and read API or Technical Docs
In this article, I will share my strategy on how to find and read technical documentation. While most articles help you read well-written, well-maintained docs, I will share my approach on how to navigate a not-so-friendly docs (Monaco Code editor) with an example from my project query.cafe.
For this topic, I also made a Youtube video to show you some examples!
Unfortunately, I can only see a few comprehensive articles and videos to learn the “reading strategy”.
So, now there is one more article to help beginner developers. Let’s dive in!
Why “read the manual” skill is essential but underestimated?
Most people can read, and it is the brain assuming it can read anything easily. Therefore, most beginner developers don’t even realise they don’t know how to read the technical documentation effectively. Reading is handled by default by our System 1 because it is a habit and a primary skill.
Also, generally, technical documentation is dry and not visually attractive; even though I believe the team behind the documentation devote lots of effort to make it as straightforward as possible. Because it is boring to read those materials, we tend to skip them. (My favourite Docs are MDN Web Docs and Google API Docs)
That is why we ignore the “read the manual” skill. However, only in real work, we know its importance. Those documents are the most reliable, updated source of information regarding the technology (language, framework, modules, library) we are working on. If the technology is mature, there are many tutorials and unofficial articles to go to; so we can compare and don’t rely much on the docs. Yet, if the technology is newly developed, the official documentation is the only choice.
My strategy to find and read technical documentation
This is not the “one size fits all” strategy because different materials are written differently. Yet, there are some common things and patterns you can rely on to navigate the docs. Moreover, most docs assume that readers have a reasonable level of understanding of technology and syntax.
KNOW THE DOCS
Similar to reading a map, you must get yourself familiar with the legends and navigation. There are many things in the docs homepage, some are descriptive, some aren’t, but I usually care about a few things first.
Scan the page and remember the navigation
As mentioned, there are many things on the homepage with tabs, links, sections. They are very descriptive; so to save time for your next visit; you should let your mind wander and scan through those sections to remember briefly what each section is about.
Version
Most cases the version you downloaded are the latest version, so the docs by default support the latest version. However, for example, Python 2 and Python 3 are equally popular, so you should check your project specs.
Tab “Docs”, “API Docs”, “Getting Started”, “What is…”, “About”
These are things you come to the page for. You want to know what this doc is about and if there are solutions for what you are working on. They also show some use-cases in tutorials so you can get some hints on what function you should look for.
You can’t miss these tabs, and they are usually used universally across docs.
“Tutorials”, “Playground”
In these tutorials, you can build small applications using technology. These tutorials cover the basics, but you can learn the documentation pretty fast just by completing the tutorials.
Search bar of the page and Brower search (Ctrl + F)
The simple yet powerful tool! I usually have a specific thing to look for in the documentation page. I don’t want to be dragged away by the details on the page.
Firstly, I use the Browser search to see if what I look for is available on the main page (most likely not but it’s worth trying). Then, I use the Search bar of the page to find from the page directory.
For example, on Monaco code editor, I want to find a function to help me with “value” displayed in the code editor on query.cafe. So the keyword is “value” or “setvalue” or “set” or “update”.
With search bar, you should be creative and play the keyword game like you do with Google.
STRATEGY
- Read with a purpose. Know what is the expected behaviour/ output of the code you want to write.
What problem are you trying to solve? There are two scenarios here to consider before diving deeper into the documentation.
If you are looking for feature-oriented or problem-oriented solutions, you should go to complimentary (Google, Stackoverflow, Github Repo, Youtube tutorials) sources first. For example, you want to build a code editor in your web application. Documentation can’t guide you through the process on how to build it, where to start.
Documentation is only useful when you have a bug to fix, or you look for technical instruction to write a function to do a certain thing.
2. Know what you are working on
A string, an array, displaying value issue, handling output value of a method, request from/to the server, …
3. Some common categories “Event”, “Functions”, and “Classes” are used to group the information.
4. For Functions, you should look for what Parameters you need to give, Syntax, what Output and what Type of Output it gives back.
It is essential to know the output from a function because it will link to what you can do next with it.
Also, remember to look for “Events”, “Classes”, “Functions” tab referred from the current section you are in.
If you have other tips on how to read a technical document, please comment. I think others will find it helpful too.
