Monthly Archives: August 2012

techpubs tools writing

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.

What’s New in Conversation and Community?

Conversation and Community 2nd Edition Cover

Love this new cover, both photos are Creative Commons licensed once again. Let’s look between the covers though!

While thinking about the second edition and how three years had passed, I was pleasantly surprised that we could get to the three year mark with the book’s content remaining relevant and accurate. Seems nearly impossible on such a fast-moving topic as the social web. Yet while looking through the tools chapter to update it, we mostly tested URLs and looked at the categories. Surprise, nearly all example tools are still relevant and useful to technical documentation. Not all the exact examples still existed, but that was just interesting to revisit.

Next, I examined the book for three areas of improvement – organization, content updates and additions based on my most recent experiments and experiences with OpenStack at Rackspace.

Reorganization

With the tools being so much more a part of every  day life and work now, I have moved the “Concepts and Tools of the Social Web” chapter to become an appendix. It also lets readers go right into “Defining a Writer’s Role with the Social Web” where I walk through a strategic approach to the social web. I also moved an entire section about managing community methods into a new chapter titled “Analyzing and Measuring Web Techniques” to expand on the management practices and business value tie-ins.

Additions

Some of the best additions to the book are interviews with practitioners I’ve met over the years who are doing community-based documentation already. It’s a balanced mix of open source communities and corporations using community to add value to their offerings. These are scattered throughout the book. I answered these same questions as well about how my current work is structured.

Based on my observations with documentation comments over the last year and a half, I added plenty of commentary and guidance to “Commenting and Connecting with Users.” Selecting and implementing a commenting system is chockful of requirements and guardrails for comments included on every page of your documentation. I also give an example of how to process comments daily, weekly, and moderate comments.

I added some additional information to the wikis chapter based on my recent experience with a Google Summer of Code documentation summit, comparing and contrasting “typical” wiki writing to planned writing. Many wikis have become web content management systems that encourage collaboration, so while I continue to address wikis in a separate chapter, the community and conversation building remains at the heart of my book. For wiki-specific tactics using Confluence, I’d highly recommend Sarah Maddox’s book, Confluence, Tech Comm, Chocolate, which I reviewed previously.

I added a chapter about content strategy for community documentation. I’m definitely sensing a strategic specialty opening up right now, and want to keep exploring it through the lens of content strategy. There’s a great case study included as well about Autodesk and their learning communities. An interview with Victor Solano with Scot Abel lets you “explore how the software giant has leveraged the power of the crowd, software standards, and content management to meet the fast-changing needs of its customers.” I found it thought-provoking and inspiring.

If anyone would like a signed first edition, please let me know by sending an email to annegentle at justwriteclick dot com. We’ll work out shipping and payment (Paypal or check-in-the-mail) with the few remaining copies I have!