Q and A from MindTouch Webinar: Managing Teams of Writers

Questions from the “Managing Technical Writing Teams” webinar

On March 4, 2011, MindTouch sponsored a webinar titled “Managing Technical Writing Teams.” The webinar was a conversation between Scott Abel, The Content Wrangler, and Richard L. Hamilton, author of the book, Managing Writers: A Real-World Guide to Managing Technical Documentation. A replay of the webinar is available at: Managing Technical Writing Teams webinar replay.

Participants had the opportunity to ask questions, but we were unable to answer all of the questions in the time available. This page contains the questions that we didn’t get to, along with answers from Richard.

Q: I will soon be the manager of a new hires (I will hire them). I have not formerly supervised in the past, and am the only person who can mentor, train, and develop the writers. Do you have a few tips for someone in my position?

A: Good luck 🙂

Here are a few thoughts:

  • Make absolutely sure you understand what your management expects. Ask them, repeat it back to them, document it, and confirm it as time goes by.
  • Make absolutely sure that your team understands the same thing.
  • Work with your management to make sure that they understand that getting a team going will take training and time to get up to speed, and lobby hard and early for both.
  • Build strong relationships with your peer managers. They are a team, too, and in addition to being folks you need to work with all the time, they are also a great source of experience and information. Most will be glad to help mentor you as you get going.
  • Hire experienced people, but avoid know-it-alls or “my way or the highway” folks. You will need to build processes, which will benefit from experience, but you also need flexibility.
  • Build your processes and select your tools with your team. The best way to avoid resistance is to engage your team in your decisions. You actually have an advantage starting from scratch, since everything will be new to everybody, and you don’t need to move folks from an initial position, but you still need to get them on board.
  • Get some training and read some books. There are basic management skills that you need to learn if you’ve never supervised in the past. I’m a big fan of W. Edwards Deming’s “Out of the Crisis,” which is a classic. John Kotter’s “Leading Change,” and “Power and Influence” are also excellent.
  • Don’t overmanage. People will usually do just fine if you point them in the right direction, give them good tools and processes, and leave them alone.

Q: I wanted to buy your book to read on my Nook, any chance BN.com will have it available?

A: I don’t know if we will sell the eBook through bn.com (though we do sell the printed book there), but we will have an ePub version of the book available for sale soon, and that should work on the Nook.

Q: POLL: It’s hard to narrow it to just one role, and I suspect the same is true for many others on the call! 🙂

A: I understand, most of us wear many hats. I’ll make sure MindTouch is aware of this for future webinars.

Q: Two questions: I was just at a conference where Research In Motion talked about their HelpBlog for Blackberry — when questions appear a lot, they make new FAQs. How do you know when a frequently asked question is really a usability issue? AND to what extent do companies view tech doc as part of usability?

A: You can probably make a good case that nearly any question reflects a usability issue, so the challenge really is determining whether a question highlights a usability issue that is big enough to be fixed in your product/service. If so, the FAQ is a good place to post workarounds, but you really need a product fix, not a documentation fix.

To determining whether you need a product fix or a doc fix, I would consider the following:

  • Frequency: How often is this happening in real life (not how often your engineers think it will happen)?
  • Impact: What is the impact on people, property, or data? Also, what is the impact on your company’s revenue? (You can bet that a problem that keeps people from buying your product will get a quick fix.)
  • Cost: What does it cost to fix the problem?

While the decision as to what gets fixed and what gets documented is probably not in the hands of the documentation team, technical communicators should be prepared to provide input to that decision, which means you need to be able to evaluate and prioritize usability issues, and defend your evaluation.

Regarding the second part of your question, I don’t have enough first hand information to give you a definitive answer. My perception is that too many companies see documentation and usability as distinct disciplines and view the former as a necessary evil and the latter as a lot of hand waving. Possibly a cynical point of view:-), but I have seen companies where the attitude for both is “do the least we can get away with.” That said, there is a great deal of synergy between these two disciplines, and a good documentation team ought to be consistently thinking about (and acting on) usability issues.

Q: That was my next question — I wonder to what extent people want increasingly to consume “help content” in documentation vs. socially.

A: I’m not sure people think about it that way. We, as writers, talk about “help content,” and we make distinctions between documentation and social media, but I’m not sure that our customers think in those terms. They want to use our product/service for some purpose, and they will get information wherever it’s most convenient to do so. That may be why generalized search engines, like Google, are so popular; they are likely to find what you need, regardless of where it lives on the web.

That said, I think there is a human tendency to look for information from people we trust, and social media provides more avenues for establishing (or losing:) trust. To the extent that people prefer social media, I suspect it’s because they have the ability to interact with others and judge their reliability. They also have some assurance that a bad answer will get shot down in short order.

One thing I would do, which is separate from the question of documentation vs. social media, is to get as much documentation as possible out on the web in an accessible, easy-to-search form. If you can do that through a venue that offers the benefits of social media, even better.

Q: How/when will we know whether we got a free book?

A: You should have heard from MindTouch already if you will be receiving a free book.

Q: Do you have some specific suggestions for proving the value of a tech writing team to others, such as Development managers?

A: Here are a few suggestions:

  • Be visible: A great role model is Anne Gentle, who is a visible part of the team at Rack Space. How many technical communicators are active participants in a company’s public presence (blogs, twitter, etc.)? Not nearly enough. Anne is the exception. Go over to RackSpace.com and search for “Anne Gentle,” or check out her blog at JustWriteClick.com and you’ll see why.
  • Be active: Even though it takes (and often seems to waste) time, be part of the project team. If your company is using Scrum or another agile methodology, make sure you’re a pig and not a chicken (if you don’t know about pigs and chickens, check out The Chicken and the Pig on Wikipedia. Attend project meetings and keep up your relationships with your peer managers.
  • Be helpful: In the webinar, I described a situation where the writing team worked with the support team to create a unified support/release notes document. That was a case where improving the process for developing a deliverable reduced the work for both organizations. Look for (and implement) ways that your expertise can help the company as a whole. Another area that’s worth looking into is participating in writing specifications. Often the information in specifications is directly applicable to your documentation, so why not get involved early and help out the development team?
  • Be aware: Make sure you understand the constraints your peer managers have, especially schedule constraints. Try to schedule doc reviews around the busiest times (difficult, but not impossible). Front load as much as you can; for example, review outlines and structure early in the process, not when engineers are fighting last minute bugs.

Q: What is the key software a technical communicator should have in their arsenal? With so many packages on the market, seems like companies expect you to know them ALL.

A: There are a lot. 🙂 Rather than suggest specific software (with one exception), I suggest you consider the following:

  • XML: Learn about XML. Learn why it’s important and get familiar with at least one of the free/cheap editors. You can get a free copy of XML Mind (xmlmind.com) for personal use, and you can get evaluation copies of nearly any other XML editor out there.
  • Social Media: Read some blogs, get a twitter account and follow some of the tech comm folks on twitter, and check out a wiki or two. Everyone knows about Wikipedia, but many don’t know that anyone can edit most of the pages out there. Blatant Plug: Anne Gentle’s book, Conversation and Community: The Social Web for Documentation, is a good resource for this. MindTouch is sponsoring a webinar with Anne on April 8, and they will be giving away copies of her book. For more information go to: MindTouch Webinars.
  • Microsoft Word: As an open source advocate it pains me to say this, but every technical writer should know how to use Microsoft Word. It is simply too ubiquitous to ignore. Get familiar with using it correctly, and learn how to take advantage of its automation capabilities. (Another blatant plug: XML Press is coming out with a new book on Microsoft Word this year. Check our website, XML Press, for the latest).

I know it’s not the way many hiring managers work, but I am much more interested in a person’s ability to communicate than I am with his or her ability to wrangle a particular tool. If you can build a good portfolio that highlights your strengths and shows that you can handle both structured and unstructured content, then the tools should be of secondary importance.

Q: Since it doesn’t look like you are going to have time to answer questions before the hour is up, will you answer them and send us the answers afterwards?

A: Yes, and here they are 🙂

Q: How do you convince project teams to bring on the writers at the beginning of the project instead of waiting until near the end and expect the writers to bail them out?

A: Don’t wait for them to ask you. As a manager, you should be working with your peer managers on the project teams so you know what’s coming up. You can then assign writers to those projects (I know, they are busy doing other things, but if you want to be involved at the beginning, you need to devote resources at the beginning).

Q: A couple of relevant links: tinyurl.com/ykaa9rh tinyurl.com/4h5molb

A: FYI, these links are, respectively, a review of my book, “Managing Writers,” and a review of Michael Lopp’s “Being Geek: The Software Developer’s Career Handbook.” Both reviews are by Richard Mateosian, who reviews books for IEEE and on his blog XRM Content. I haven’t read Lopp’s book, yet, but I am a fan of his blog, Rands in Repose.

Q: Will this presentation be available for download later?

A: Yes, you can find it at: Webinar Replay Link.

Q: How do I justify the roi for a tech pubs dept?

A: Managing Writers has a chapter titled “Building a Business Case,” which goes into this in detail. You can also get some good information in a few recent blogs, including:

Q: How do you handle “control” issues with other departments, for example, trainers who want to own their own training content vs collaborating with Tech Comm? There seems to be tremendous cross-over on the content.

A: We humans seem to have an ingrained need to “own” things, don’t we? If your question had been asked by a training manager, I suspect he or she would have had problems with the tech comm team’s “ownership” issues. It just depends on where you stand. 🙂

I don’t think there’s an easy answer. I’ve seen things go smoothly when the two teams have common management or when they are closely integrated, but that’s probably the exception. Like many management problems, I think this one comes down to communication. Spend time with your training team peers, and start a conversation about effective ways to work together. I suspect you’ll find that they understand the importance of sharing; the problems appear in the details of how you work together. If you can get agreement on the general principle that you should work more closely, pull a few people from each team into a group and have them look at ways of working together. It won’t be easy, but the more time you spend together, the harder it will be to justify separate development processes.

Q: I started in tech writing because I was bored and the software we were using had horrible docs

A: Not sure if there’s a question there, but trying to fix horrible docs is as good a motivation as any. 🙂

Q: Can you speak to managing documentation teams in an agile development environment? It certainly presents challenges.

A: It is a challenge. I have managed teams that work in an ancestor of agile that used rapid turnaround and 2-4 week “sprints,” but I have not worked in an true agile development environment. So, take what I say with a grain of salt.

That said, here are a couple of suggestions from people I trust:

  • Be a pig: Agile has the notion of “pigs” and “chickens.” The analogy comes from cooking. If you make ham and eggs, the chicken is involved, but the pig is committed. In an agile environment, pigs are full members of the team, and are part of the decision-making. Chickens are involved, but are not critical to the project. If you’re not a pig, you will probably be ignored when things get busy (and they will).
  • Don’t be shy: You will be in a lot of very short meetings. You need to be assertive about what you need and what you can deliver. Scrums (those short meetings) are not a good time to hide in a corner, nor are they a time to deliver a dissertation on the importance of technical documentation. Make your points, concisely and clearly, then step back.
  • Experiment: Because sprints are short, you can try something out in one sprint and discard it for the next one if it doesn’t work.

Q: What are the benefits of using social media vs. collecting feedback via links inviting users to share their experience with the doc?

A: The main benefit is that social media makes it easier to engage in a dialog. While inviting user feedback through a link is a good thing, it is a one-way communication path. What makes social media so powerful is the many-way communication it enables.

Q: Can you recommend a best practice to provide multilevel documentation that can be sent to customers but has hidden information that is for support only? We use FM/Docbook. Diane – San Jose

A: Create a separate section in your Frame template for “hidden” information, mark that section using conditional text so that you can remove it when you create user deliverables, and make sure everyone knows that anything not in that section will go to customers. Then, when you create your deliverables, make sure the support organization reviews your documentation for “leakage.”

All that said, I suspect that over time there will be less and less information that you will really want to keep from customers. Making the process a little (but not too) difficult will help ensure that you only put things in the hidden section that you really need to keep private.

Q: Why are documentation, support, and learning departments so siloed?

A: Human nature. We like to own things, and we like to control the things we own. That is good, in the sense that we generally take responsibility for the things we own, but bad, because we protect the things we own from others. Thus, we end up with silos.

Managers have a big part in building and maintaining silos. The sad fact is that nearly all managers give lip service to tearing down silos, then reward individual behavior that builds them, usually because their own managers do the same.

One side effect of intelligent use of social media may be the breaking down of silos. It makes sense that increased communication among internal organizations, along with the need to have a consistent face towards customers, may help break down the walls. And, competitive pressure that doesn’t allow for duplication of effort could have an impact, too.