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



  1. It’s definitely a mindset shift, writing in an Agile environment, one I tried to cover on my own blog a while back (http://www.onemanwrites.co.uk/2007/09/19/trickle-vs-traditional/).

    Good luck though, it’s a fun way to work if you buy into it!

    Comment by Gordon — December 2, 2009 @ 10:33 am | Reply

    • Gordon, I definately agree that increased contact with the dev team and more involvement in the day-to-day development of the product are some of the benefits of Agile.

      But since I’m a lone writer, I still get to ‘own’ my docs. 😉

      Comment by heratech — December 2, 2009 @ 1:23 pm | Reply

  2. Luckily for me, I converted everything to Docbook–and then to DITA–before we started the shift to Agile. Unluckily for me, I’m the only one doing all the content and documentation! But even in a one-man show, Agile really helps me grasp the scope of the necessary documentation. Sometimes there is a ton of work, but at least the model allows me to be involved from the beginning and voice any concerns about documentations scope.

    Thanks for an enjoyable read. I’ll be following your posts.

    Comment by Chris Vickery — December 2, 2009 @ 1:12 pm | Reply

    • Chris, I’m a sole writer too. And I can’t even fathom trying to make a shift to DITA while working in an Agile environment. Everyone I’ve spoken to about the conversion process says that there is a lot of work that needs to be done, even in previously structured writing, to get completely ported over to DITA.

      Comment by heratech — December 2, 2009 @ 1:18 pm | Reply

  3. […] This post was mentioned on Twitter by Mike Cottmeyer and Agile Journal, Ibrahim Saracoglu. Ibrahim Saracoglu said: RT: @mcottmeyer: Interesting post… Preparing for Agile – Modular Writing http://bit.ly/7IBQNi […]

    Pingback by Tweets that mention Preparing for Agile – Modular Writing « HeraTech -- Topsy.com — December 2, 2009 @ 7:44 pm | Reply

  4. […] Preparing for Agile – Modular Writing (Julie Stickler) […]

    Pingback by Dew Drop – December 3, 2009 | Alvin Ashcraft's Morning Dew — December 3, 2009 @ 8:08 am | Reply

  5. […] – Making Major Revisions As I mentioned in my previous post, some of my legacy documentation needs some Tender Loving Care.  I had to solve the problem of how […]

    Pingback by Techniques for Being Ready-to-Publish at Any Time « HeraTech — December 3, 2009 @ 8:45 am | Reply

  6. […] Preparing for Agile – Modular Writing […]

    Pingback by Agile Tenet #3 – Deliver Frequently « HeraTech — December 22, 2009 @ 8:10 am | Reply

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: