I am going to reference several projects throughout this post as both positive and negative examples of following the guidance I’m laying out; these are illustrative examples and I hope it is clear that I’m not passing judgement on these projects. Documentation is hard!
Cover Image Photo by Kimberly Farmer on Unsplash
Intro
I’m going to be saying some opinionated things in this post, so to help get you on my side, I want to try a thought experiment.
Pretend that you suddenly need to get up-to-speed on a new framework or library, within a short amount of time and without guidance. Maybe you just got assigned to a new project at work or started a new job. This is minute zero, and you are sitting at your computer, unfamiliar with this new “thing” and looking to get started.
You type “{name_of_thing} documentation” into your preferred search engine and hit enter. You end up on the official documentation website and you are presented with the following three links:
- Quick Start Guide
- Handbook / User Manual
- Complete API List / Low-Level Docs
Which one do you click on? Keep in mind, you are short on time and the pressure is on to get productive with this new tool quickly.
If you are like me, you are smashing that Quick Start Guide link as fast as possible.
Once I’ve started spending some time in the project, I’m probably going to be perusing that Handbook and/or User Manual. Finally, I might reference the full API docs from time to time.
Yet…
What I seem to consistently find is that too many projects focus on documentation in the reverse order. They have beautiful full API docs, generated through some bespoke automated process, they might or might not have a handbook or manual, and the “getting started” guide is often insufficient, outdated, or simply omitted entirely.
This should not be the case.
Thinking of Documentation Levels as a Funnel
I’m not an expert on this, but to me it seems like you can categorize most types of documentation by their technical level and degree of abstraction. E.g., on the high-level end of the spectrum, you have a step-by-step tutorial that a completely novice can follow. On the other end, you have the actual source code and any comments contained within.
I would argue that these levels of documentation are also closely correlated with how long you spend with a given piece of technology, so you can view the levels of documentation not just as a pyramid of abstraction level, but also as a funnel:
I am aware that this graphic is not an exhaustive representation of every type of documentation
Examples of Higher-Level Documentation
Again, I’m calling out these projects as illustrative examples, not to shame them or cast judgement in any way. Also, things change; these projects might have improved their docs since this post was published. Anyways, here are some links to documentation that, in my opinion, neglect the top part of the documentation funnel:
For an example of a project with (again, in my opinion) excellent higher-level docs, check out:
Why More Effort Should be Put On The Early Part of the Funnel
This post started with a hypothetical scenario, in which you are an employee looking to get started ASAP using a new framework or library. I’m hoping that this alone was pretty convincing of why high-level documentation matters, but here are some additional thoughts on the topic.
Jobs Have Changed
It used to be very common for developers to stay in a given job for many years, perhaps even spanning decades. Nowadays, for a multitude of reasons, you see more and more developers only spending a few years at a given company. And for those that stay longer, often they are switching teams and/or projects more frequently than before. With these changes in position often come changes in the developer’s day-to-day tech stack, meaning there are more developers trying to learn new things all the time.
On a related note, even when staying in the same role at the same company, it seems like technology stacks are still changing faster than ever (especially in the web space).
All this is to say that the funnel pictured above has been flipped 180 degrees from how it used to be. With more new developers entering the industry, more projects competing for use, more switching between stacks, and an increased urgency for getting “productive” with new things faster than before, the higher-level parts of the documentation funnel have become a bottleneck and core area of focus.
Your Documentation is a Form of Marketing
Those familiar with the term “Developer Advocate” probably already know this, but documentation is actually a form of marketing for most large projects. This is particularly the case when developers are trying to decide between multiple competing options.
Going once again back to the concept of a documentation funnel, if your high-level documentation is terrible, you might get developers abandoning your project before they have even tried it.
Source Code Is More Accessible Than Ever
This is more an argument for spending less time on the lower-level part of the tech documentation funnel, not necessarily more time on the upper part (although it should free you up to do so). My argument is that access to the actual source code of a given project is easier now than ever before and this access can often mitigate the need for (exhaustive) lower-level docs.
There have been many times where I have had a question that required a deeper understanding of a framework than the docs were able to provide; usually the way this went is I would spend 10+ minutes struggling to find the answer in the official documentation, give up and just open the source code on GitHub, use search + jump-to tools to navigate to the relevant code, and get my answer directly from the code.
In these instances, it often takes me only minutes to find the answer via source code, whereas I could have spent half-an-hour with the documentation and still not had a complete answer to my question.
I’m not saying that you should completely omit lower-level docs (such as auto-generated API docs), but that they are slightly less important than before and your time should be spent accordingly.
Why Are High-Level Docs Often Neglected?
It’s easy for me to say that more quality high-level documentation should be produced, but another thing to have it actually happen. Why is higher-level accessible documentation often neglected?
Writing at All Levels is Tough
The short answer is that writing quality documentation takes time, effort, and ability.
I would argue that writing high-quality high-level (abstracted) documentation tends to actually be more difficult than writing low-level documentation, which is a big part of why it is often neglected. This kind of falls into the same paradigm as the fact that often experts in various fields are not the best teachers – it is one thing to understand something at a very low level, but an entirely different can of worms to be able to translate those concepts and communicate them effectively to an audience with a range of different technical abilities and background.
Exploiting The Rise of Tech Blogs and Community Posts
This idea bleeds into the next section, when I rant about React’s documentation, but my argument here is that it seems like many large projects are neglecting their higher-level docs, because they know that tech bloggers (like myself) and communities like dev.to will pick up the slack and fill in the gaps. Why bother writing a “How to get started with ___” guide, if 500 different bloggers are all going to write their own version of it anyways?
Although I’m generally OK with this for projects that are not very profitable, I have a few issues with it:
- It can lead to misinformation
- I have seen a number of community-written guides on various pieces of technology which contain information that is undeniably incorrect, and at times, dangerous.
- It is using free labor
- Again, for smaller projects that aren’t turning a profit, I’m OK with this. But for large projects, with millions in funding, this feels super exploitative and just wrong. Hire more tech writers!
Don’t Overdo It
As much as I think focusing on the early part of the funnel is an important part of modern documentation development, I have also seen a fair number of instances where it has gone too far in that direction.
The best example I can think of for this is the official React docs (sorry Dan!). React has often sold itself as a beginner-friendly framework, so it is not that surprising that the docs reflect that (I have even heard stories about bootcamps teaching React before teaching JavaScript…). But I would argue that React has gone too far in focusing on the early stages of the funnel, to the detriment of those using the framework past the “getting started” stage of learning. The majority of their official documentation, even the “API Reference” sections, are written with a high-level of abstraction and tend to gloss over a ton of lower-level implementation details, which is great for getting started with React, but leads to too many developers not being aware of the nuances and (many) footguns that come with React.
I think that part of why this is the case with the React docs brings me to another point about insufficient documentation; I have a feeling that Facebook / React are exploiting the open-source community to write their docs for them for free, especially the lower-level docs. The best documentation I have read on React rendering has all been written by people outside the official React team. If you google things about React beyond the surface level, most of the results are not the official docs. I don’t want to go on too much of a rant here, but Facebook / Meta is basically a money-printing machine and it upsets me that they, and others, are exploiting free labor (although that is far from the worst practices – I’m not a fan of FB if you can’t tell 😉).
Throwing Stones
Look, no one is perfect and writing good documentation is hard. Writing “perfect” documentation that pleases everyone is likely impossible. I’m not perfect, or anywhere close to it, so I know I haven’t always followed my own guidance here. And I don’t expect every project to have the time or resources to do so either.
This post is mostly just some food-for-thought. Happy snacking.
