Saturday, February 14, 2015

typokiller: my new tool to exterminate typos in software documentation

Last year, during the Django Sprint we had in Kraków, I was working on finding and fixing typos in the Django Documentation.

It was fun to automate spellchecking the docs, but it was also very laborious to use my rudimentary tools.

This week, in a span of 2 nights and 1 morning, I worked on a minimally usable version of typokiller. The first outcome of this work was this Pull Request made just a few hours ago.

Even though typokiller is still an alpha-quality baby project, I am pretty happy that it has an interactive terminal-based UI, thanks to the awesome termbox library:

With typokiller running, a bit of patience and about 1 hour of careful inspection I was able to find 45 typos in OpenShift Origin's documentation. As you can see in the screenshot I had to go through 1583 potential typos. Thank God I implemented replace all, edit all and ignore all commands :-)

The idea behind typokiller is to have several small programs each responsible for one of these steps:

  1. Collect documentation excerpts
  2. Check spelling
  3. Interactively fix typos
Right now typokiller only supports inspecting the documentation of Go code, but I might include support for more languages in the future (or you can create and issue to tell me which language you need, or you can code it and make a pull request).

You start with a Git repository with some project containing potential typos in its documentation. You might want to create a new branch. Then you can run:

$ ./killtypos $(find /path/to/project -type d -not \( -name Godeps -prune -o -name .git -prune  \))

This will find all directories inside the project path, ignoring the subdirectories Godeps and .git, and pass that through the 3 stages of typokiller, leaving you in an interactive mode. After inspecting the potential typos, type "a" to apply the changes to the files. Review the files with Git, commit, push and make a PR.

The design was made such that I can pipe the output of one command into another, and also easily integrate with other unix tools like head, grep, etc.

That's all for now, let me know if you enjoy typokiller.

No comments: