The Adventure Continues…

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? 

Adventures in Scenario-Based Documentation

Back in June, I posted about a new initiative my technical writing team planned to adopt. It’s called Scenario-Based Content, a strategy that fits our work as technical communicators into the abbreviated schedules typical in an Agile project.

If you read the June post, you’ll remember I was perplexed by the idea. I wasn’t sure how Scenario-Based Content was any different from the task-based content we were already developing.

In the time since June, we’ve had some training and opportunity to practice during a certification process, which I just completed today. My impression? Scenario-Based Content just may be the answer to several questions.

How are Scenarios Different from Tasks?

Scenarios should align with user stories. For example, “I want to recover my protected server from a disaster even though I don’t have the disaster recovery option.”

This user story was my certification project. The solution to recovering this server is not a single task. Rather, it is about ten tasks, about half of which are optional, depending on outcomes of prior tasks, as well as on the specific configuration of the environment where the disaster occurred. All of these tasks were already written and included in our product’s Admin Guide. But we never addressed how users might actually read those tasks or we’d have know how difficult they were to follow.

I took apart the monster section and organized it into baby tasks. My first requirement for certification was to design a flow chart that explains the scenario. This, as it turns out, was crucial for my own understanding of the process.

The process, as originally written, had so many conditions, I kept losing my place. Distilling it down to something that could be expressed by a standard diamond decision shape required nesting conditions, which in turn, showed me where to break out the various optional procedures.

Armed with a list of baby procedures, it occurred to me that I needed a mechanism for guiding readers back to the main path through the flow chart. I added a What Should I Do Next section to every task in the scenario.

Can Scenario Documentation Truly Fit Inside an Agile Cycle? 

I was skeptical about this until I tried it for myself. At the same time I was practicing for my certification, I was also assigned to a new product team. This new product has several sprints already scheduled. I read the user stories planned for each sprint and began setting up scenario content shells ( I don’t have a working UI yet). Right now, I have three major scenario shells, which I may further break down, once I see how complex the UI is that supports them.

What astonished me was how much of this new product I already understand and it was just kicked off. With our old process, I wouldn’t have reached this point until several months into the year-long production cycle.

Will Scenarios Document the Whole System?

In a comment left after my June post, “Techquestioner” said scenarios may not show you the whole system. I think this is true to a large extent but hasten to add I don’t think that’s necessarily a bad thing.

Here’s why:

The Admin Guide for one of my products is nearly a thousand pages. How frequently do technical communicators lament the fact that no one is reading our work? This is due primarily to our insistence that every detail be covered. The problem with that approach is most people will never have need for all of those details. For example, my product works on all Windows operating systems dating back to XP. But if some users are running Windows 7, they have no need for all the XP details.

Sure, we could debate publishing baby books for each OS version over the merits of single-sourcing, but the point remains the same – we’re giving them too much information.

Scenario-Based Documentation focuses ONLY on the information needed to solve the problem described in a very specific user story. If there are twenty fields on a UI dialog, but only three of them are needed in a particular scenario, then only those three are documented. The balance will be documented in some other scenario until, eventually, all fields are documented.

Aren’t We Doing Double Work? 

Got me there. Here’s one problem with Scenario-Based Content: Help Systems are still UI-centric. If I click a Help button on a screen, it means I need help on that screen. I don’t want to have to click through a dozen scenarios until I find the one that contains the instructions for completing the one field I need.

So I still see us documenting software screens separately for Context-Sensitive Help systems in addition to Scenario-Based Content development.

Based on what I’ve practiced and applied so far, I like the Scenario-Based Content approach.

How are you documenting software in Agile environments? How are you addressing the problem of fitting UI-centric Help screens into a scenario-based model of development?