Yihui Xie

Perhaps My Documentation is not Too Bad

Yihui Xie / 2018-02-07


As usual, I started my morning by going through new Github issues, and I saw a nicely written issue in the xaringan repo. It was a great issue because there was a minimal reproducible example in it. However, I thought the issue should be easy to understand because I had documented the css argument on the help page ?xaringan::moon_reader. So there were two possibilities:

  1. My documentation was poor.

  2. The user didn’t read the documentation.

It turned out the second possibility was true. What a relief! I’m glad that I didn’t yell “Why don’t you read the documentation?”

Why don't you read documentation?

That said, as software developers, we should always keep the first possibility in mind. Documentation is hard, and sometimes harder than developing the software itself.