Read The Docs, like a novel?

Posted on April 12, 2018 in rants

I've picked up a habit only recently - go through the entire documentation of a library/utility before trying it out.

Once I have read, not glanced over, sat down for 30-60 minutes and read the documentation, I start from an index file - such as __init__.py for python modules or main.c or similar names, and follow the hints. If they are sparse, I look for a largeish file or resort to randomly opening a few files until I am looking at lines that are not boilerplate code.

If I feel confused with the mental models or names/ labels used in the docs or the code, I choose to stop. Maybe put it on a check-later list, and move on. However, if I survive reading through all the documentation for that library or utility (preferably) in one go and the code did not confuse the living daylights out of me, it is a good sign that I can understand and use it well.

Bummer that my memory isn't too great for verbatim recall, but having a good idea of what the tool can or cannot do and any gotchas buried in the docs really helps while trying the first example. I may not remember every option, but I know if I'm barking up the wrong tree long before I download or install anything. I have wasted week, nah months, trying to wrap my head around tools that are beyond a single human's capacity to fully grok.

The process of reading the docs in their entirety doubles up as a good "integration test" for the docs "running on" my mind.

You may want to experiment too and ask these questions while you read the docs and code:

  • Is the license suitable for my use? (hehe, no really)
  • When was the code last updated? Is that relevant?
  • Do the mental models and names make sense?
  • How many different pieces of trivia/ pop-culture/ memes am I expected to know?
  • Are individual modules, classes, functions documented?
  • Do the docs have self-contained examples, or only contrived fragments?
  • Is there at least one tutorial-style example?
  • How many contributors are interested? (may be relevant for production use)
  • If there are any pull requests, what are pending (new features!)
  • Which issues/ pull requests were rejected, why?
  • What is the general the tone for communication from contributors?
  • Are any codes of conduct mentioned? Do these rules seem enforced?
  • Do the authors explain their intention and values for this project? Do you strongly disagree with any?
  • What kind of shortcuts/exceptions are made? Are they explained?

If this feels like a waste of time, try finding out the answers to these questions six months deep into using the library or utility for an important project and then try backing out of it. It is (not) fun :P

P.S. https://readthedocs.org/ is brilliant, use it and support it!