The Adventure Continues…

January 6, 2012

Not so long ago, in a galaxy on an island not so far away, a technical writer faced a horrible truth…

Her development team did not like working with her because, they said, “…the content she delivered was always wrong.”

First, she got mad and tried to explain that she was working without a thorough understanding of the product’s benefits, and in many cases, working without access to the product (!). She was developing procedures based off requirements documents created for various gate reviews and her only means of communication with her team was email. No one told her things had changed since those documents were written, even though she sent her work out for review. Instead, they pushed her out of the loop and just wrote their own content.

True story.

January, the time of year when everything is new again, marks a number of organizational changes. New job roles, a new technical information process that had to fit into a new agile software development process, new team members, new bosses, everything’s new, NEW, NEW! For some people, this much change produces anxiety, but I am embracing them like another New Year’s Eve party.

As of a few days ago, I am now an Information Engineer. While I’m sad to see Technical Writer go the way of the dinosaur, I love the new moniker because it better explains how my role has changed I’ve kept up with the changes in this field.

This is a key point: I don’t think we can afford to wait for others to hold our hands and tug us to the next level. We must drive Technical Communication beyond the confines of the user manual. This means taking responsibility for learning new tools, following technology trends, taking risks.

When I first began working in this field, I remember hating to ask questions, afraid the perception I was creating was one of someone who didn’t know her job. Today, I consider this the number one tip on a What Not To Do list. I now ask questions constantly – it’s how how I learn. The answers to the questions I ask frequently take my thought processes into new directions – directions I would not have taken on my own. Asking questions is THE most important thing I do each day.

This is handy because one of the changes my employer is making is an ambitious initiative to completely transform technical information. We’re not writing manuals anymore. Instead, we’re writing very specific and focused scenarios – think articles – that include just enough information for users to solve a particular problem. Articles align with an Agile project’s user stories and can be ported into any number of information sets including books, Wikis, Help Systems, etc.

Sounds easy, right?

That’s what I thought.

In practice, identifying the content to include in an article has proven extremely frustrating for a number of reasons:

  • My brain is stuck in book-mode. I figure it’s going to take my brain a while to stop thinking linearly. I must consciously think of what information a user needs to solve the problem at hand and no more.
  • Agile user stories don’t neatly align to my work. This, I believe, is a growing pain. Frequently, the user stories the development team writes are way too granular for my work and are better suited as steps in a procedure, which in turn, may be part of my ‘article’.  I then thought I should try to map all the Agile user stories to the appropriate tech info article, but found many of them have no technical information impact. For example, back-end coding requires tracking so a developer creates a user story for it, but there is no corresponding UI function. It’s entirely code-based and automatic. I now focus on only the user stories with a UI function.
  • My work crosses over sprints. I planned to document the user stories in lock step with the code developed in any given sprint. This has been working well for developing outlines but not for review-ready drafts. Again, I suspect this is a growing pain that will resolve itself as the development team gains expertise using Agile methodologies. So, for Feature X, I may be able to document only Adding X in Sprint 1, Deleting X in Sprint 2, and Modifying X in Sprint 3. This is perfectly fine, but it taxes a brain (see bullet 1) still stuck in Book Mode that wants to document the entire feature.

All these frustrations had me convinced I’d be hearing a sequel to the sad story I shared above. Instead, something cool has come out of it. During a conference call with my product manager this morning, we were exploring a new software tool the team is adopting for Agile tracking purposes. The tool was slow, subject to frequent hanging and eventually crashed. To fill the wait times, he brought up some concerns with various technologies and how they could impact our development efforts. To my astonishment and his, I not only knew his concerns, I understood and could contribute to the discussion.

This is a significant achievement – we’re only a few months into this project. For me to have this level of depth so early into the process is nothing short of miraculous. He pointed out that the team is now ASKING me questions instead of simply copying me on emails.

And this is only the beginning. I’m excited to see how an entire project developed and delivered using our new processes will be received by our customers.

What changes are you facing this year? Do they excite or terrify you? 



  1. This year threatens to be interesting. I’ll be providing on-device documentation for several smart phone applications. There are several problems with this, the first being that these applications are supposed to be so intuitive that they don’t require any explanation. The second being screen real estate. And the third being the complete and total lack of tools for performing this function.

    It’s got to be light weight. It’s got to be installed with the application (integrated with the app). And it’s got to fit on multiple screens and be easy to read. What works for that? The only thing I could come up with was raw HTML with a CSS for navigation. So that’s what I’ve done. It looks good. It gets the point across. It’s entirely task-oriented. I’d say from the looks of things that I’ll be making more of them. It certainly doesn’t terrify me. I guess I’ll have to say it excites me. It’s kind of fun working in HTML again.

  2. Thanks for your comment. Smart phones, tablets, etc., are coming up in discussions here, too. Delivery mechanisms are – and will continue to be – a critical component of our transformation initiative. I’ve been examining places where I can chunk up my content into what I am calling ‘info atoms’ – small, manageable, reusuable chunks that – by themselves, may not be useful – but when assembled for use in various media, provide exactly what users need to solve their problems.

  3. Great post, Patty and a good reminder for me. There are still lots of technical writers, er, information engineers still stuck in “book mode”. It will take a bit of time before everyone morphs into writing modularly and focusing solely on topics (articles) that focus on precisely what the reader is working to achieve at that point in using the product and nothing else.

    I applaud your evolution. Keep it up.

  4. […] and blogger (Write Trends) spoke of her recent experience in embracing a new title for herself: information engineer. She spoke of letting go of being a technical writer, just as I have been trying to let go of being […]

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

%d bloggers like this: