Since I’m using JIRA to track writing assignments, I have to live with a few compromises in terminology, but so far I like the system. Here are some details of how I’m using it.

Each item in JIRA is an article. I add only articles that we’re really going to write. (For general ideas that may one day be something we write, I put the ideas elsewhere.)

I assign the JIRA items to the writers who will write the article. If there is no writer, I leave the article unassigned.

I give each article a story point weight of about 10 points. Another section of JIRA allows me to define specific sprint release windows, and I organize sprints (based on weeks) to accept no more than 70 story points. This means that each sprint can only have 7 articles, assuming each article is 10 story points. However, I can also adjust the story points for each article. For example, short articles might be 3 story points, while longer articles might be 15 story points. Adjusting for the appropriate number of story points helps us avoid over-allocating work for the week.

In the JIRA item, I try to outline the general ideas the article should cover. I also add comments about each item, and the assignee  receives an email notification with each comment and edit.

When an article is completely finished and published, I change its status to Resolved. Or if we decide to not do the article, I resolve or delete the article. The resolution statuses include Fixed, Will Not Fix, Duplicate, and some others.

I can assign different priorities to the articles — 1, 2, 3, 4, or 5. A priority 1 is called a “blocker.” Priority 2 is called “critical.” Priority 3 is “major,” and so on. (Here’s where the terminology doesn’t quite fit for writing assignments.)

JIRA’s filters are robust, but I am using them in a simple manner. I create a filter to show all items assigned to each intern, and then I save those filters as bookmarks. When I review and plan articles with the writers, we just select the JIRA filter and go down the list of what they’re working on.

I’ve tried various ways to organize and track writing assignments, and so far this one seems to work well. Of course no system works if you don’t actually use the system, and no system is perfect. I used to have little slips of paper pinned all around my cube. I’ve also tried Excel spreadsheets, as well as SharePoint.

But using JIRA to track writing assignments is particularly beneficial because familiarity with JIRA helps out with our involvement in project teams. In our IT department, many project teams use JIRA, and familiarity with JIRA makes it much easier to stay abreast of project news, releases, bugs, issues, and other details. Often the lifeblood of a software project is captured in JIRA, since this asynchronous sharing of information helps everyone on the team remain aware of what’s going on.

One thing I’m not using JIRA for is to manage the actual documents. While I could upload file attachments, I find that Dropbox is much easier. Dropbox is almost like a net file share drive. I could spend an entirely separate post describing how much I love Dropbox, but so that I stay on track, I’ll just say that I try to name the Dropbox folders the same as the JIRA item titles.

One other shortcoming of JIRA is that it doesn’t allow me to change the statuses of items in a customizable way (at least I haven’t figure out how to do it yet). I’d like to indicate various states of the article as they pass through the approval processes, but alas, the issues in JIRA are either Open, In Progress, or Resolved. (Perhaps it’s best to keep it simple.)

I’d be interested to hear what system you use to manage and track writing assignments.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

The changes had a lot to do with location. Previously, each technical writer was embedded in a specific group. Most of us were stationed on different floors, in proximity to the developers, interaction designers, quality assurance engineers, and project managers for each project.

This proximity was useful for staying in the loop with project information, but it did nothing for our technical writing team. We used different tools, didn’t follow a common style guide, and came up with our own processes and content models.

Because we wanted to try to build some momentum towards standards, we decided to consolidate our group, sitting together in the same row of cubes. We were no longer embedded within specific project teams, but rather centralized as technical writers in a common location and shared throughout the organization.

In the previous embedded-writer model, I looked longingly towards our once-a-week meeting with technical writers, holding it as the highlight meeting of the week. But now that we were sitting together, it was like a team meeting all day long. Coordination and morale skyrocketed.

As the weeks passed, we started to form some standards. We decided to standardize our toolset, first of all, so that in case one writer won the lottery and left the organization, another writer could seamlessly fill the gap. After weeks of research, and through the luck of another group that already purchased the solution, we adopted and implemented a new help authoring system. We then attacked our style discrepancies, and quickly adopted a 42-page guide of stylistic decisions.

We were gaining momentum fast, and acquired our own servers to run help, injected a documentation template into the project manager process, formulated a content model for help, designated a team member to be the tools administrator, and more. We were flying as a team. We even stopped holding team meetings because anytime we needed to meet, we could just swivel our chairs and raise an issue. Our close proximity led to a brilliant flow of communication.

In the back of my mind, I knew that we had lost some rapport with the project teams that we no longer sat next to. But it didn’t hit me how detached I had become until, about a year later, I attended a two-hour meeting with one of my projects and found that I had nothing to say at all.  All the momentum I had previously accrued as a key project voice seemed to slip out from under me.

Proximity and Communication

Sitting silently in the project meeting, not contributing towards interface text, nor quality assurance, nor jumping in on broken functionality, nor even on training strategies, I realized that my sacrifice of proximity with the project team had resulted in my impotence on the project team. I no longer had the same voice, nor was I someone anyone paid attention to. I had become that quiet fly-on-the-wall technical writer, the one whom no one expects anything from except a help file.

I’ve learned that proximity to any team makes an incalculable difference in the role you play with that team. Grouped together with other writers, we actually formed standards for the first time in years. We  felt like a team. And separated from project teams, I fell off their radar, and they off mine.

This, then, is what I’m calling The Proximity Problem. The closer you are to a group, the more you interact with that group. But you can’t be everywhere at once, so you have to choose the group that gets priority. Given these dynamics, is it better to be embedded within project teams or within a technical writing team?

Comparing and Contrasting Benefits

Embedded within project teams, I did much more than technical writing. I logged bugs, critiqued designs, guided project managers with feedback from users, and was generally go-to guy for new team members who want to ramp up on the project. I became a subject matter expert on the app itself, which led to my being a key member with a voice at the table.

Embedded within the technical writing team, I didn’t get sucked into all of these secondary roles. I could focus on my primary contribution: the help material. But not having involvement in other aspects of the project, such as the design, testing, interface, planning, and so on, made it harder to write help. I was often a latecomer to information, finding out at the last minute about upcoming releases and stumbling into new pages with changed functionality.

Sitting with my colleagues is heavenly. We understand our kind. We engage in heated debates about style controversies, and sometimes crack jokes about how bad interface text is. We ask each other questions about Author-it and Camtasia. One of my colleagues even brings in peaches to share, and has his own candy store. It’s comfortable to sit with them, and share in the camaraderie.

But in the larger scope of agile development, this isolation from the project conversations that are happening on an ongoing basis seems to have negative consequences. The isolation away from other writers, as I sit near developers and other IT members, might be worth it for the end result. The problem is that projects are often short durations, so I would need to be nomadic for the model to work, moving from one project group to another as my project load shifted.

Perhaps nomadism would be ideal for help authors. When working on project X, sit next to project X. When working on project Y,  sit next to project Y. And yet, even despite the improbability of such an open seating model, it seems archaic in a day of virtual collaboration and remotely located workforces. Why insist that maximum productivity is only gained by rubbing elbows with your team all day long? Surely asynchronous methods of communication, real-time online interactions, and regular meetings using VoIP or the telephone can compete with the benefits of nearby seating.

Alternatives to the Dilemma

Despite the logic of embedding myself with a project team, where very likely I’m the only technical writer present, I’m not ready to give up our new-found team momentum. We’re making a lot of progress towards standards and tools, processes and styles. Once the dust settles, we may return to our former model in which we’re embedded in project teams.

Still, perhaps I’m holding out for another reason: I’m not convinced that proximity is essential to keeping up with project information. I’m not persuaded that there aren’t equally viable ways to gather the same data and interact, because if nothing else, the Internet has shown us how remotely distributed people can be closely connected with each other. The Internet has pulled us loose from our physical relationships, distancing us from those immediately around us and drawing us closer to others whom we never see or speak with. Email, instant messaging, Internet Relay Chat, webinars, podcasts, blogs, websites, text messages — all of this enables communication to take place despite physical boundaries. Theoretically, proximity shouldn’t be a problem. But teams who already enjoy proximity have no need for virtual communication tools, so outsiders often feel the need to participate in close proximity model to keep in loop.

It’s true that proximity does lend itself to more immediate updates. When you’re sitting next to a developer and he makes a shout of joy when he gets something to work, you’re updated. When you’re sitting next to a tester who groans each time she finds another bug, you’re updated (that is, if you ask what the commotion is about).

But it’s still possible to stay updated sitting remotely, away from project teams. And this is precisely because nearly every team in most IT groups uses some form of bug tracking tool, such as JIRA, Team Foundation Server, Fogbugz, or something else. Nearly everything gets logged somewhere, and if we take the time to stay close to it, to follow it as carefully as we might read a novel, tracking comment threads, attending meetings, reviewing sprint plans and roadmaps, checking IRC logs, design and requirements documents, listening each day to scrums — if we did all this, we could circumvent the proximity problem and perhaps even stay more aware than team members in the same cube aisle. That is, as long as distance doesn’t deafen our ears, make us forget our priorities and workloads, and lull us into a false belief that nothing much is going on.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

Who is to blame?

In one of Alistair Christie’s recent podcasts, he interviews his 70-year-old mother about how she uses computers. Although they cover many topics in the interview, her tech guilt is the most salient part of the discussion. She blames herself for not understanding how to work computers and navigate websites.

When she can’t locate certain features on an interface (for example, Paypal), her first inclination isn’t to blame the bad user design of the site or software, but to think that somehow it’s her fault for not understanding.

The self-blaming attitude reminds me of a passage I read in Authentic Happiness years ago. Happier people, the author wrote, don’t blame themselves when things go wrong. Rather, they tend to see others as responsible. I’ve often reflected about this, most often while playing basketball. After throwing a “bad” pass that my teammate misses, I used to say, “Sorry,” or “My bad” — blaming myself. But after reading the book, I decided that it’s the other’s fault for not catching the ball. The pass was decent enough. Embracing this attitude, I feel better about myself.

However, clearly this attitude fails in other contexts. Not taking responsibility for blame is one of The Five Dysfunctions of a Team. Team members must take responsibility for both successes and failures, and not play the blame game. The same is true in marriage. No matter how much you may have initially resisted a decision, if you relented and went along with it,  you can’t jump ship when the result is disastrous.

It seems, then, that at times you should include yourself in the blame (such as with teams), but other times you should not. The next time you’re frustrated with software, do you blame yourself for being “technically stupid”? Or do you blame the developers for the idiot design? The answer reveals a lot about how you view yourself.

Blog Sponsors

• 3Rabbitz book
• Webworks ePublisher
• Scriptorium
• Help Generator help authoring software
• Southern Polytechnic: Information Design and Communication
• Simplified English
• MindTouch
• Madcap Software
• Dr.Explain
• Adobe Technical Communication Suite
• Congree

The work keeps piling up -- who can do it all?

Sebastian asks,

I have been searching the web for information about how to divide workload among writers as the the workload–and the department itself!–grow. I am thrilled to find your blog! I am a new writer in a Health Information Systems doc group. We write for 120 products, maintain 600+ documents (several output formats). Do you know of any effective strategies/tools/medications?

What kind of documents do you produce?

We produce online help, how-to guides, quick reference guides, manager’s guides (procedural content), introductory guides (conceptual content), release notes, configuration guides, known product issues, tutorials….

Do you do translation too?

Translation/localization of deliverables seems to be evolving here. There is an international department who have a couple of writers . . . What happens might be translation but is not certifiable localization.

Any other factors that caused the increased workload?

I think what broke our system was an acquisition that increased department size by about 50%. Our lead writers had been coordinating work across product families, but the definitions of product families have gotten a little too fluid, and the workload has gotten so huge that we can only do part of what’s needed, so there’s now a backlog and it’s growing, and we’ in the midst of this move to AuthorIt, which adds work in itself…. We’d like to know what really big teams do to keep everything coordinated.

Our 50% increase did include some writers, and I know that part of the chaos comes from trying to train people on new products at the same time they’re trying to meet deadlines. But I think if I could condense the problem to a single category, it would be about coordination and communication–knowing what’s going on across that broad range of products, having the workload allocated so that the deadlines are distributed reasonably, that sort of thing.

Did the 50% size growth include an addition of new writers?

I guess I envision that other groups have tools of some kind that automate this kind of tracking, or they have some information-exchange routine, or a set of job assignments that somehow pull all the information together and keep the workload balanced.

I’m using an online project management system for tracking how hours are spent, spreadsheets for trying to balance workload (don’t even ask–corporate decisions prevent us from using a single tool for both types of tracking), lead writers for keeping up on product family information, and all kinds of meetings–methods that worked when there were 12 of us but that don’t seem to work now that there are 18.

Dear Sebastian,

Thanks for writing. I’ll share my thoughts and others can build on them in the comments if they have anything to add.

Get Professional AuthorIt Training. About AuthorIt, one thing I recommend is that you get someone to come in a provide training on it. It can take months before you feel comfortable with a robust product like AuthorIt. When I was in Florida, a colleague at another company was moving to AuthorIt (from RoboHelp). She hired Char James-Tanny (helpstuff.com) to come out and provide 3 days of training. It worked pretty well. I would recommend that training for your company too, unless you already have AuthorIt gurus.

Set Up AuthorIt Templates. I also recommend seting up AuthorIt templates and styles for the entire team to use, or even pay the trainer to come in and set them up. This can reduce the learning curve.

Insert Writers Early On in Software Development. As far as distributing the workload, inserting the writers into the software development process early is always best. That way they can stay in the loop through the entire process and be better aware of changes and other information that affect documentation. It’s the last minute emergency documentation needs that stress writers out. Or being expected to write documentation without complete information and access to the product and SMEs.

Deliver Only What Users Want. You can also survey your users to ensure you’re actually delivering the help content they want. If they only want online help and a short quick reference guide, you might do away with the long printed manual. (See this post for more info.) Of course, if you set up the AuthorIt templates and styles right, single sourcing to print shouldn’t be too arduous.

Provide a Style Guide. Having a simple style guide helps avoid the guesswork of technical writing. When writers know what style is expected, they don’t have to spend time making stylistic decisions. (But don’t go overboard with a 200 page style guide. Keep it short and sweet.)

Lighten the Editorial Process. If you have a tedious editorial process, I’d recommend getting rid of it. At one company I worked, we had an editor that required multiple submissions, requiring at least 3 weeks total for reviews and edits. It slowed the process up a bit (although granted, the quality increased). Short peer edits are more practical in my opinion.

Have the Manager Meet with Each Team Member Weekly. A good manager can help allocate resources well, and make sure each writer has an appropriate amount of work — but only if the manager is in tune with each of his or her team members. One time I had a manager who met with each of us for 30 min. to an hour a week. The outward purpose was to get a report on how we were coming along with our projects. But it transformed into much more than this, as we wandered into tangents and talked about other things. I found this one hour with my manager each week to be the best thing a manager has ever, ever, ever done. Honestly, it built rapport. It let the manager know exactly what the workload was for each of us. It allowed us to communicate any problems we were having, either with access or with reluctant SMEs. No tracking software can replace face-to-face communication.

Market Your Department. If you need more resources, you should let upper management know. If they don’t want to pay for more tech writing resources, then push back on the deliverables, the timeline, or the scope. How are you marketing your dept. to your organization? Consider getting together the key senior leaders for a dog and pony show about the benefits of good documentation.

Publish in a Place You Can Update On-the-Fly. Are you publishing your help on a server separate from the application? When you have control to continue modifying the help once the product is launched, it removes a lot of the burden of a deadline. In my situation, I give the developers a link to the help. The link points to a Flare file that I have hosted on a SharePoint site. It works well because I don’t have to stay up the entire night before a release creating video tutorials. In fact, by release time, I just have to have the basic help content out there. I can continue adding to it after the release date.

Another Perspective: Take Your Time

I don’t know quite how to say this, but good documentation takes time. Rather than always trying to do everything faster, better, with fewer resources in less time and with double the quality, etc., consider that a slower, more labor-of-love-type approach isn’t necessarily a bad thing.

I’m not recommending that you join the Slow Movement, but there’s something to be said for taking your time with a project you’re heart is in.

One of my favorite movies is Brother Sun, Sister Moon. It’s by Franco Zeffirelli and from the hippy-era, and definitely dated and corny, but it gets me every time. Here’s the song I like most.

And a round version.

The key line is this:

If you want your dream to be, take your time go slowly. Do few things but do them well — heart-felt work is holy.

I’m engaged in a lot of activities, and sometimes I see my life getting stretched thinner and thinner. In addition to being a father of 3 young girls, a husband of a voracious blogger, young men’s president in my branch, I also post regularly on my blog, publish a podcast, coordinate a social news site, and occasionally I teach courses on WordPress and do freelance web copy/design. I also love to play basketball, go on Saturday outings with my family, and read nonfiction tech content. This past week, I said to myself, Tom, focus on what you really want, and simplify your life, because you’re not doing any of these activities particularly well.

I think the same can be said for documentation. Focus on what really matters — the application that’s going out to 20,000 users, or the one designed for the highest-paying customers, or the application that generates the most calls to the support center. Give that your highest priority by doing it first. Then work on the less important tasks. (It’s the Stephen Covey big-rocks-small-rocks principle.)

The other stuff will get written eventually. The world won’t stop. This is the one comfort to being a tech writer: while your work is valuable and incredibly important, no one is going to delay the product launch if you aren’t ready.