Open Help Conference 2012 Introduces igor

I’m at the Open Help Conference in Cincinnati this weekend. Yesterday Florian Nadge from RedHat gave a lovely talk about Writing for Translation.

Next up was Warren Block, longtime FreeBSD contributor, Automating Documentation Proofreading

What tests of your doc can be automated? Many. He culled common misspellings from bug reports and his own knowledge. He used the AP style guide and wrote an algorithm from it. He found some word usages that usually need re-writing. Then he bundled it all up in a perl program called igor.

Writing Style Tests

you and your – look for too many uses
should – try to take out wishy-washy language if the user MUST do so
obviously and needless to say – can be offensive to many people, sounds like you’re talking down to the reader
starting too many sentences with “the”
e.g. and i.e. – nearly always used improperly with incorrect commas, also typically used backwards “for example” and “that is”
No examples – man pages require examples so you can flag on the lack of them

DocBook Tests

Rules different for different projects, but you could write the rules to put in a check for these.

  • Whitespace
  • Indentation
  • Tag usage style
  • Title capitalization – Uses AP Style Guide.

Program is called, igor, the lab assistant. Written in perl. Regular expressions all the way down. You can use the “ports” system:
/usr/ports/testproc/igor
or get it at:

http://www.wonkity.com/~wblock/igor

Usage: igor -R -y chapter.sgml | less -RS

On my Mac, which has perl 5.12 already installed, I downloaded the files from that directory, rename the igor file to igor.pl, and ran it against an OpenStack source file with this command:

perl -w igor.pl -R -y ~/src/openstack-manuals/doc/src/docbkx/openstack-compute-admin/computescheduler.xml

This is what I get in return:

computescheduler.xml style check:
"you" used 2 times
"your" used 3 times
"You" and "your" are informal and subjective.
Try to be formal and objective: "the file" rather than "your file".
"should" used 3 times
Use "should" sparingly, it is feeble.
Try to be imperative: "do this" rather than "you should do this".
"the following" used 2 times
If something is following, the reader can see it without being told.
"e.g." used 2 times
"E.g." (Latin "exempli gratia") means "for example" and is mostly
used in academic and scientific writing.  Consider replacing with the
more common English words.  Both forms are usually followed by a
comma for a verbal pause:  "e.g., a b c" or "for example, a b c"
"i.e." used 5 times
"I.e." (Latin "id est") means "that is" and is mostly used in academic
and scientific writing.  Consider replacing with the more common
English words.  Both forms are usually followed by a comma for
a verbal pause:  "i.e., a b c" or "that is, a b c"

I can take this set of “critiques” for this chapter, revise the chapter, and add quality and consistency! Pretty nifty.

One comment

  • Bruce
    January 22, 2013 - 8:44 am | Permalink

    “that’th very nithe, thur… ” said igor :-)

  • Leave a Reply