December 2, 2009

Preparing for Agile – Modular Writing

Filed under: Uncategorized — heratech @ 8:56 am
Tags: , , , ,

Legos If an Agile Sprint is designed to complete releasable code within a 2 – 4 week time frame that means that as a technical writer I should be aiming to have releasable documentation within the same time frame.  The question is how to accomplish that goal?

Whether I would be releasing manuals or online help, it seemed to me that the answer lay in producing modular writing.  My technical writing instructor had taught us to write short topics, preferably of a page in length or less.  This was presented as a usability feature, so that when viewing online help users wouldn’t have to scroll, and when viewing printed manuals, they wouldn’t have to flip the page to complete a task.  I’ve since learned that this style of writing stand alone chunks is referred to as “modular writing.”  I like to think of it as having lots of little Lego®  blocks that I can assemble into whatever form of documentation is required.

Ever since I worked for a company that had been investigating converting their documentation to DITA I’ve been chunking my content into Concept, Task, and Reference topics.  Even if that distinction is made only inside my own head.

I consider Concept topics to be my product overviews, application overviews, business or industry specific concepts, product specific concepts, and other overview material.

When I write procedures, they are always task oriented, and thus Task topics.

I write Reference topics when I’m documenting the UI, (for example listing all the icons in a toolbar) or writing lists of reference material, for example, statuses, commands, or configuration settings.

Now comes the fun part.  *I* write modular content.  But the legacy documentation I had inherited when I started this job was not quite as modular as I would like.  The company had originally had a very competent technical writer, but after she left the company there had been a variety of people contributing to the documentation effort, and as a result the doc set needs quite a bit of Tender Loving Care.  There were two or three separate procedures lumped under a single heading (“Creating and Deleting Widgets”). There were tasks that were buried in paragraphs of text instead of being presented as numbered steps.  There was concept information nestled within the steps of procedures.  And there were topics that stretched on for pages.  How was I going to address these problems in an Agile environment?

I found my solution when I was exposed to the concept of code refactoring in our SCRUM meetings.  According to Wikipeida, “Code refactoring is the process of changing a computer program’s internal structure without modifying its external functional behavior or existing functionality, in order to improve internal quality attributes of the software.”

I’ve adapted the idea of Code Refactoring to my process of ongoing document revision and improvement.  If the developers refactor only when they are touching a particular part of the code, I have decided that I will refactor only when I’m touching a particular part of the doc.  Our documentation is manuals, so when I open a particular chapter to fix a documentation bug or add new content I work on cleaning up the rest of the chapter while I’m in there.  So, for example, when they add a new report to the product, I might do the following to the Reports chapter of the User Guide:

  • Tear apart and revise any topics that need to be re-chunked into Concept/Task/Reference
  • Ensure that each task has a separate heading
  • Rewrite any headings that are not descriptive or task based (the dreaded “Overview” topic and “Settings” topics are ripe for revised headings)
  • Reorganize the topics into a more logical flow
  • Remove any topics that are no longer relevant (reports that are no longer shipped)
  • Add new topics as required (new reports, missing content)
  • Update screen shots if necessary

The hardest part of this process has been wrestling with my own expectations for document quality.  It is painful for me to ship documentation that doesn’t live up to my own high standards.  I want to fix everything NOW.  But I don’t have the time to do that, especially now that I’m only working two days a week.

I’ve had to trust that eventually I will have the opportunity to refactor every part of our documentation set.  As long as there is continual gradual improvement (kaizen) I can feel like I’m doing my job.


Modular Writing Resources
Single Sourcing: Building Modular Documentation By Kurt Ament

Blog at WordPress.com.