Typos in your Documentation?
2011 / 03 / 04 — documentation, spellcheck, typos, yard
More likely than you think.
Having good documentation (internal and external) can make or break bigger projects. Good documentation helps skilled users/developers get up to speed with your project. However, bad documentation will drive potential users away. Typos are probably the most embarrassing thing to find in documentation.
One day I was fixing a trivial bug in my code for a new-user, and glanced over the documentation. Low and behold I spot a typo right above the broken method. In this moment of embarrassment (in front of the new-user), I said enough is enough, no more typos!
Since I use YARD for all of my projects, I decided to write a YARD plugin which would scan all of my documentation text using the Hunspell spellchecking library (via ffi-hunspell). A couple days later, yard-spellcheck was printing typos with file-names, line-numbers and ANSI highlighting.
As I suspected, I was able to find and fix a handful of typos in my own
libraries, thanks to
yard-spellcheck. Next, I started scanning larger
projects with YARD documentation. I found a couple typos in
DataMapper and even
YARD itself (all are fixed now).
The lesson of this short story is that typos are lurking everywhere; too numerous and well hidden for human eyes to catch them all. Luckily, we now have an automated-tool in the fight against typos. The Ruby Community is notably obsessed with testing and quality of software, we should feel the same way about our documentation.
$ gem install yard-spellcheck $ cd my_project/ $ yard-spellcheck