Library Writing Realizations (2015)

I wonder if he has hard data about how often people look at his documentation.

I generally agree with everything he wrote. One page quick start, focus on getting things working, people will dig into writing code right away. Yes, yes, yes. But, then what? People tend to read documentation extensively when something doesn't work the way they think it should. You can make your API as self-documenting as humanly possible, but there's no way to know if the person using your API is going to be on the same wavelength.

My go-to example here is Ruby. I once got stuck on an interactive ruby tutorial because you're supposed to be able to guess the names of the commonly used functions in ruby. This particular tutorial wouldn't let you pass until you figured it out. I had to google it. For whatever reason, it was not the word I would have chosen. The word they chose makes complete sense in hindsight, but it's simply not the word that comes to mind to me.

I kept running into that again and again with Ruby and later with Rails. I just wasn't getting it. The documentation became very important for me to get anything done.

Well, that makes two of us. I'll actually just go inspect the source code a lot of the time since docs can be wrong, but the docs are still good in that case to help provide an overview.

What absolutely needs to be present is some sort of index of all functions/data types, ideally with a link to the underlying source code. Don't make people try and guess what your library exposes.

I read the docs too. Great docs can spell the difference between using your code and giving up or finding another solution. If you're new to a particular language or programming, code with great docs can also teach you how the language itself works.

Tabulator (http://tabulator.info/docs/5.3) is the last example that comes to mind, had to use it earlier this year.

The first step in vetting a new dependency for me is always documentation (not just taken at face value but also how well it corresponds to reality). The more complex the functionality and the larger the scope, the more it matters.

First, since writing a library is a lot about design, and design is about communication, documentation provides many indirect but useful signals. Second, no project (whether dev-to-dev or dev-to-end-user) exists at a discrete point in time, and as every piece evolves documentation will be critical for making it manageable, especially if the project is not something done for hire.

Even when people don't read the docs, it's often not a matter of unwillingness to - but them not expecting relevant docs to exist in the first place, or being unable to find them with the keywords they can think of.

Being able to link said docs saves on having to re-explain everything from scratch when asked questions - helping contextualize and give background to a terser answer, assuming the docs don't answer the problem outright. They can also be helpful to refresh my own memory when explaining things, or when I'm trying to remember how to use my own code.

I read the docs too, though generally a minimally working example / quick start is where I'll stop unless I run into issues.

That's another thing not to do when writing a library: including and discussing code examples of incorrect usage. Personally, when I read documentation, retaining incorrect code examples is literally the last thing I want to achieve.