Journals by RSS
Journals by EmailI’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.
How I Fit the First Time Around
When I was hired as an intern by my current employer, the team was in iteration twenty-something of a big, complex software project that had significant documentation needs. They were following an Agile methodology using scrums. The business analyst who acted as my supervisor gave me a document that explained their iterative development, which involved groupings of iterations into cycles. He asked me to create stories and tasks in the tracking system the team was using and chunk my work such that I could complete tasks each iteration. The analyst would review my work each iteration and give feedback.
The development manager decided that since the online help was part of the software, the results of my iterative tasks had to be tested and passed off by the quality assurance team after the business analyst reviewed it. Since the manual was part of my work, it would go through the same process. Different team leads have held to that idea with varying strictness.
What I Learned
I found that the way UI-development user stories and tasks were broken up didn’t have a one-to-one relationship with task-based procedures or with context-sensitive help topics. As a result, it became difficult sometimes to chunk my work in ways that made sense for testing. For example, some development tasks may have had impact across multiple screens of the application, while others may have required a single sentence to be added somewhere in the help or manual (not enough work to justify a full task).
In addition, after the initial release, the team began releasing at the end of every cycle. Because designers and developers could be making changes up until code freeze, and because the users wouldn’t be seeing new docs until the release anyway, I decided that it didn’t make total sense to adhere to the iteration deadlines. It was more important to make sure my content was created, reviewed, and tested by the end of each cycle. That gave me more time to deal with changes. A hardening period before each release became very helpful for me.
Further Projects
Some of my colleagues work on a project where some aspects have been outsourced to a third party who has tried to push the code development process on documentation development—as if it were simply a matter of putting the same clothes on a different child. Only in this case, the children have completely different shapes and sizes, and what fits one has caused restriction and discomfort for the other. Documentation cycles of writing, editing, review and feedback, and publishing don’t match coding processes exactly. So they need to be allowed their own schedule to some degree.
The portfolio I work in has implemented an arrangement called micro-teams, where two Java developers and a tester work together on development tasks. This is an arrangement where it doesn’t make sense for me to be in a micro-team; I’m not always going to have something for a tester to test, and there’s only one of me in my portfolio. Therefore, my role is a support role to multiple micro-teams.
What’s It All Mean?
If you’re moving from some other field into tech comm, or graduating from college and hunting for a tech comm job, do your best to learn how to fit into your team. Talk to technical writers in different disciplines—software, medicine, science, and so on—and find out how they keep pace with their teams.
Particularly in an Agile software development environment:
- Plan out the general length of help topics or other chunks of content.
- Determine how long it will take to get the content through the writing and review cycle.
- Find out whether management expects the content to be ready at the end of each iteration, as of the regular code freeze, or when the code is released.
- Work backward to see how the documentation cycles work within that.
- Negotiate if necessary.
If you’ve got some experience behind you, you may have some hard figures to offer (“It takes four hours of work to complete the cycle for a topic; therefore I can complete X topics in one iteration”) or at least have some anecdotal support for your preferred methods.
Different managers will react differently to your suggestions. Be ready to adapt. Fortunately, I’ve worked for project managers who weren’t interested in micromanaging my work; they were interested in the results. As long as I came up with the results on time, they didn’t worry about how many days my documentation cycle took. So they learned to trust my methods.
Related posts (auto-generated):
