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

Sometimes it’s hard to make the real name of an application stick.

In our organization, development projects are given a certain name, and the resulting application at times is supposed to have a different name. This probably wouldn’t be a problem except that, due to Agile methodology, we are in frequent contact with the stakeholders. Therefore, they hear the development team refer to the project by the name that the development lifecycle has been given. There are times when the final software’s name hasn’t been agreed upon yet, so all there is to call it is the same name as the dev project.

However, because so many people talk about the project using that name, it becomes difficult to then change mindsets and call it by the application’s real title later on.

I see this as one of the challenges for the documentation. I’ve got to pick the right name—but which name is the right one? The official name, or the one that most people are using?

› Continue reading…

Bookmark It

Hide Sites

The Agile development methodology for software development involves creating and testing pieces of a product in small periods (called iterations or sprints). It is contrasted with the waterfall process, which is more of one requirements-gathering effort followed by development and then testing, and finally a single release. This methodology is gaining popularity, and it presents certain challenges for technical communicators. Having worked in my organization’s flavor of Agile for a few years, I’d like to offer a few suggestions for Agile survival.

Challenges for the Agile Writer

For the suggestions to make sense, first I’ll explain some challenges. In a waterfall process, when all requirements are written up front and are specific, the writer has something fixed to go from. We can use the requirements document to do some writing ahead of time so that it’s not all left until the end when deadlines are imminent. In Agile, requirements are not completed at the beginning, but as the project progresses, and are written in the form of use cases or user stories. This form of requirement describes a function that the user is supposed to be able to perform using the software. The developers then build that capability into the product. (In our flavor, we have interaction designers and sometimes business analysts to help gather specific requirements for user stories and tasks and then design how the features should be built.)

Agile releases take place regularly, so the writer has a short amount of time to produce documentation. Granted, the amount of functionality per release is smaller, but Agile lends itself to fast-paced development, which means fast-paced documentation. There is only so much time to document the new features.

› 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