Reading the Documentation for Popular Products

The Physics of "Getting Started"

What do flask.Blueprint, requests.Session, and ansible.plugins have in common?

They all share two curious properties:

• In the official documentation, they are relegated to the "Advanced" section.
• Any production use case of the relevant technologies (flask, requests, and ansible) would use them.

All of these technologies are popular for their niche. All of them have friendly "Getting started" guides.

Those guides do not cover the relevant piece, the piece that makes this technology usable in most realistic cases. Most people who use these technology start with "Getting Started", and follow the path it suggests. The path it suggests eventually breaks down.

When this path breaks down, often people will think to themselves "I don't need the advanced stuff. My use case is pretty vanilla." They will shim and work around the limitations, until either giving up on the whole enterprise, or asking an expert.

At the point where they asked an expert, the expert will be exasperated. "Just use flask.Blueprint/requests.Session/ansible.plugins for anything beyond a toy example. This is the way to really use the technology."

The expert is exasperated because this is the fifth (or the hundred and fifth!) time this has come. Someone is about to give up in disgust, only to learn that the solution was simple all along: the first three paragraphs in the "Advanced" section cover how to do this.

Why does this happen?

I chose these three examples because I know them well. I can give similar examples from almost every popular technology: following the "Quickstart" guide leads to a huge mess, while a fairly simple way to do it in a better way is presented in a section titled "Advanced" or "Developer" or something similar.

These things happen so often that this cannot be a coincidence. Just like the common shape of whales and fish, despite separate evolutionary origins, the explanation is the shape of the dynamic systems at play.

Whales and fish look similar because they both have to solve a similar problem: moving through water efficiently. Having an appropriate aquadynamic shape is the right solution.

Technologies, open source or commercial, live and die by their adoption. A technology that is hard to adopt is a useless relic.

There are many things that can impact the ease of adoption of a technology. One of the easiest levers to pull, by the core development team, is the "Quickstart" guide. This guide tries to get a toy example up and running as fast as possible.

At this point, any extra complexity is a big turn off. Any extra step will have a large fraction of the users dropping off. This exponential decay means that to survive, the Quickstart guide needs to be heavily optimized.

It does not matter whether it's "design" (developers explicitly optimizing the guide) or "evolution" (technologies which don't do that do not end up surviving long enough to cause problems). It is probably a combination of both factors.

As can be predicted from general optimization problems, you can optimize more when you drop constraints. Removing the constraint "must lead to a proper production solution" from the requirements for the Quickstart guide leads to a guide more optimized to win hearts and minds.

At the point the project is popular, this will end up being the shape of the documentation:

• A Quickstart guide, generating a toy example with a serious scaling flaw.
• An "Advanced" section with the explanation of how to really use the technology.

What can you do?

Being upset with Quickstart guides, as I have for many years, is like being upset with gravity, which I also have for many years. Those phenomena are annyoing, but they are the results of immutable laws of nature.

In order to fly, or use technologies, you need to first understand the physics involved and then figure out how to use them to accomplish your goals. Now that the shape is understandable, how can it make adopting technologies easier?

The quickstart guide is still useful. Follow it. Generate a toy example. Play around with it. Get a feel for the technology. See if it's at all a good fit.

Put all of these attempts in a source-controlled repository. Now move all of the code written so far into a subdirectory, experiments. Go to the advanced section, and figure out what are the 1-3 things that you need to do in order to properly use the technology. Alternatively, consult someone with experience.

Use the notes from the experiments, plus the understanding from the "advanced" section, to build your first "real" proof of concept. From this point on, this is the "toy example" you iterate on.

The experiments serve as research notes for how to do the specific things you needed. Never use the experiments directly.

Summary

Good technologies will gently nudge you to using them badly. This is not good or bad: this is a law of nature. Understand it, and start using platforms better!

Thanks to Alex Scammon for his feedback on an earlier draft of this post. Any mistakes that remain are my responsibility.