I started my current job five years ago this week. Reaching the level of senior technical writer brings me to ask whether I’ve got the smarts to go along with the time I’ve clocked.

A Narrow View of Tech Comm

When I graduated from Utah State University two months before starting as an intern, I thought technical communication consisted mainly of writing manuals, help systems, and the occasional tutorial. I thought the main activities were writing and creating images for print or Web.

My definition of a technical writer didn’t differ much from most people’s if at all.

I hadn’t heard the terms CSS, single sourcing, structured authoring, DITA, social media, Agile, RSS, SEO, or content strategy. Some of these things were either relatively new or not dreamed of at that point.

I belonged to the student chapter of the Society for Technical Communication, but the chapter members mainly learned from each other. There was only so far we could go that way.

› Continue reading…

Bookmark It

Hide Sites

I’ve been asked what the biggest surprise was for me when I went full-time into the field of technical communication following university graduation. Honestly, not a lot surprised me; I knew how to write procedures, gather information, and use Web, print, and graphics tools. I had even worked in a company environment during a short contract period following my freshman year of college.

So what was the surprise?

Basically that on a significantly sized software development team, no one really knew how to work with a technical writer. So it was up to me to educate them. Problem was, I didn’t know how they were supposed to incorporate me into their team either.

When I worked in that contract position I mentioned, it was on a team of writers and editors. Because we were dealing with content for a website, we interacted with a couple of database administrators, but that was about it. Most of our interactions were with each other and our team lead’s manager.

› Continue reading…

Bookmark It

Hide Sites

Scrums are part of the particular flavor of Agile methodology project teams use in the portfolio I work in. The managers recently borrowed the scrum concept for release preparation because the projects in this portfolio are interrelated and often have to be released together. This means that a lot of coordination is needed so that there are no surprises for anyone.

In these scrums, we have 15 minutes or so for a representative from each project team to report on the progress of showstopper bugs, testing, problems that have emerged, and so on. They usually happen during the week or two before a release (as opposed to all the time). Then, if the release date needs to be adjusted, or if a feature isn’t quite complete, management decides what to do. They still have a final go/no-go meeting, but the release scrums keep everything out on the table.

Because technical writers enjoy surprises as little as anyone else, I get invited to these scrums. This lets me know how much time I have to put release notes together and whether there are any last-minute changes I need to make to them or to any other documentation. Since some of my deliverables are deployed with the application builds, I need to know whether to remove the updates from the build before it’s released.

These release scrums have turned out to be an advantage for our portfolio. They especially help me to stay informed. If you use some variation of Agile, I recommend release scrums. Technical writers often need every resource available to know what’s happening with the release schedule.

Bookmark It

Hide Sites

Sometimes, the Agile software development methodology seems like it could be renamed the “Fly by the Seat of Your Pants” methodology. But really, it means that you need a somewhat different set of project management skills for your documentation. I could certainly improve in these skills, but here are a few I rely on in an Agile environment.

Skill 1: Topic-Based Writing

Before I describe this one, I need to point out that yes, writing isn’t exactly planning; writing is what a technical writer does after planning. Writing is a rubber-meets-the-road activity.

True, but the project management applies in the way that you plan to write. I heard it said once that DITA is perfect for Agile environments because the way writers chunk information in that scheme allows that information to be dispensed from a single source into whatever output happens to be needed at a particular time. In short, it allows writers to quickly respond.

If I could substitute “topic-based writing” for “DITA” here, I would add that another great benefit is that writing in small topics allows you to keep pace with development and to release documentation in step with the application updates. Small topics give you less work to do in the iterations or sprints and enable you to mark your progress more regularly. So plan to write small in general and then adapt as needed.

› Continue reading…

Bookmark It

Hide Sites

One of the principles of Agile development is that you work in segments of time (iterations and cycles) on chunks of functionality that can be released at the end of the segments. This encourages frequent releases, which are good for users because they get new functionality and fixed bugs more often. Obviously, the amounts of functionality and fixed bugs are smaller, but more frequent releases give a sense of progress.

I’ve been working on some release notes today, a deliverable that we just decided to add to a particular project (it’s not a standard deliverable in our department). Previously, I had a “What’s New” topic in the help system, but I was usually caught up enough with getting the updated documentation finished in time for the code freezes that this topic fell to the bottom of my list of priorities. But I like the idea of having this kind of document.

› Continue reading…

Bookmark It

Hide Sites

We have a customized flavor of Agile development, and today as I was talking to one of the program managers about the next few cycles of work in a particular project, he said that the work in the last cycle or two was not yet defined. That’s fine; at least in our version of Agile, the work that was defined generally at the beginning is solidified as we go. Development is planned on an iteration-by-iteration (or sprint-by-sprint in some vocabularies) basis and more broadly on a cycle-by-cycle basis. A cycle contains several iterations of work, and the idea is to have a body of code that can be released to and used by the customer at the end of the cycle. The interaction designers prototype at least one cycle ahead of development.

The manager hopes that most of the new development work will be done at the end of the second-to-last cycle. As he talked, I got a little idea: What if the last cycle of an Agile project were reserved for bug fixes? We have hardening periods before the release for fixing bugs and for the testers to make sure they’ve exercised and proven the functionality that was developed at the end of the cycle. But what about an overall hardening cycle for the bugs that haven’t yet been addressed throughout the entire project?

This would benefit the team and the customer, but I wouldn’t be talking about this if I didn’t think it could benefit me, the technical communicator.

› Continue reading…

Bookmark It

Hide Sites