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.