Outline

Managing Technical Documentation

Updated: 07 June 2007

Table of Contents

1. Preface
2. Part I: Getting Started
2.1. Becoming a Manager
2.2. The Elements of Technical Writing
2.3. Power and Influence
3. Part II: Managing People
3.1. Working with Human Resources
3.2. Hiring and that other thing
3.3. Motivating
3.4. Evaluating
3.5. Outsourcing
4. Part III: Managing Projects
4.1. Planning
4.2. Tracking
4.3. Working with the rest of the project
4.4. Localization
5. Part IV: Managing Technology
5.1. Living with Technology
5.2. Understanding the Limits of Technology
5.3. Avoiding common pitfalls
5.4. Using XML
5.5. Using the Web
5.6. Content Re-Use, Single Sourcing, and Modular Documentation
6. Appendices
7. Bibliography
8. Glossary
9. Index

1. Preface

An introduction to what this book is about and who it is for. The book has four major parts: Getting Started, Managing People, Managing Projects, and Managing Technology. The style of most sections is to start with a real life situation or story pertaining to that section’s topic, and draw from that situation specific conclusions and suggestions.

The audience is primarily documentation managers, but also includes writers who have to manage their own work and managers who have one or more writers on a product development or marketing team.

2. Part I: Getting Starting

2.1. Becoming a Manager

Describes how I became a documentation manager, and how I became “educated” by my team. Also discusses my philosophy of management and sets the stage for the style of the book.

Link to draft section

2.2. The Elements of Technical Writing

Many people become documentation managers with little or no experience dealing with technical documentation. This chapter provides a high level overview of technical documentation for those in that boat. It identifies seven elements of technical documentation: product, developers, audience, tasks, deliverables, environment, and schedule, and presents them from the perspective of the technical writer.

  • Link to Part 1
  • Link to Part 2

2.3. Power and Influence

The definitive management challenge for documentation is power. Documentation lives at or near the bottom of the formal hierarchy of project disciplines. Some documentation managers simply accept this; more successful ones find ways of gaining informal power. This chapter uses an example where my team was able to increase its influence on a major project to illustrate several ways to improve the position of documentation in the power structure.

Link to draft section.

3. Part II: Managing People

This part discusses the human side of managing.

3.1. Working with Human Resources

A discussion of what your Personnel/Human Resources organization can do for you, what you should expect and what you shouldn’t expect from them, and when is it essential to work with them.

Link to draft section.

3.2. Hiring and that other thing

A discussion of selecting the best people so that you rarely have to do that “other thing.” What you should be looking for when you hire technical writers, how to interview, and how to evaluate writing samples.

3.3. Motivating

Or more accurately, how to avoid de-motivating. A discussion of what motivates employees and how you as a manager can create an environment that provides the fewest possible de-motivators.

Link to draft section.

3.4. Evaluating

In most organizations, you will be forced to evaluate and probably rank and/or rate employees. A discussion of what evaluation is about, how to make it a positive experience for employees, and how to deal with the twin evils of ranking and rating.

  • Link to Part 1.
  • Link to Part 2.
  • Link to Part 3.
  • Link to Part 4.

3.5. Outsourcing

Outsourcing is a reality, whether we like it or not. A discussion of what it means to the documentation manager.

4. Part III: Managing Projects

What it takes to plan and execute a project.

4.1. Planning

  • The truth about plans. How project management uses plans and how you need to use plans to be effective.
  • How to create a documentation plan. Steps to create the plan and steps to write the plan. Who should write which parts of a plan. What form should the written plan take.
  • How to make useful estimates.
  • How to anticipate and deal with changes.
  • How to work with the project management team.

4.2. Tracking

What to track, what to record, what to report and when to report it, and how to know when you’re in trouble.

4.3. Working with the rest of the project

How do you deal with the rest of the project team; what do you need from them, what do they need from you.

4.4. Localization

How to manage translation and localization.

5. Part IV: Managing Technology

You will need to deal with at least some technology.

5.1. Living with Technology

General thoughts about technology, plus a set of guidelines for living with technology.

Link to Section.

5.2. Understanding the Limits of Technology

A discussion of what you can reasonably expect to get from technology, and how you can avoid over-reliance on technology. For documentation, the critical point is that technology is not a substitute for good research, logical organization, and good writing.

5.3. Avoiding common pitfalls

The failure rate for big ticket documentation projects, especially content management projects, is notoriously high. This section discusses why this is so, and how you can avoid disaster.

  • Understand costs and benefits. In particular, do you need that new content management system/XML authoring system/single source publishing system? You may not. Make sure there are realistic, measurable benefits before taking the plunge.
  • Understand your requirements. This is the big one. You’d think it would be obvious, but many projects founder on poorly understood, misunderstood, or simply non-existent requirements.
  • Understand your processes. Make sure you understand your existing processes before you try to automate them.
  • Plan for change. You will underestimate the time needed adopt new technology. This section discusses how to deal with that and avoid having changes and delays torpedo your project.

5.4. Using XML

An overview of XML technology as it applies to documentation. Contains a brief history, an explanation of the key concepts, a discussion of pros and cons, and a consideration of when it makes sense to use XML and when it doesn’t.

Link to Section.

5.5. Using the Web

A look at how the internet is changing documentation. In particular, it will consider delivering documentation on the web via “traditional” web pages as well as newer vehicles like wikis.

5.6. Content Re-Use, Single Sourcing, and Modular Documentation

A consideration of these topics, with an emphasis on pealing back the hype and looking at where these technologies make sense and where they don’t.

6. Appendices

I’m not sure whether there will need to be any appendices. This would be a logical place to put planning templates and checklists, if I end up creating any.

7. Bibliography

Just what you’d expect.

8. Glossary

Just what you’d expect.

9. Index

Just what you’d expect.

Copyright 2007 © Richard L. Hamilton

6 Responses to Outline

  1. Pingback: Outline Available « Managing Technical Documentation

  2. spacer Mark says:
    February 8, 2007 at 11:19 am

    Are you going to talk at all about managing outsourced doc projects, or translation issues?

    Also ,there appears to be a boble in the first bullet under section 6.3:

    In particular, do you need new that new content management system/XML…

    probably want to drop the first “new”

  3. spacer rlhamilton says:
    February 8, 2007 at 11:24 am

    Mark,

    Good points. I do need to deal with both outsourcing and localization/translation. And I’ll fix the typo, too. Thanks very much.

  4. spacer Scott Hudson says:
    February 8, 2007 at 2:32 pm

    Hi Dick!

    Based on your outline, this looks to be an extremely useful resource! How fast can you get this written? spacer

    Seriously, I think you’ve done a lot of great work on this already and I can’t wait to read the finished product.

    –Scott

  5. spacer rlhamilton says:
    February 8, 2007 at 2:35 pm

    Scott,

    The quick answer is “not fast enough” :). Thanks for the kind words. I’ll do my best to live up to your expectations.

  6. spacer Spence says:
    February 18, 2007 at 6:58 pm

    Your outline is looking good, Dick.
    Congratulations!

    I’ve got a couple of comments.
    Warning: This could turn into a stemwinder.
    I don’t do a lot of writing these days.
    I’ll try to keep it compact.

    Re: Section 3.2 – Who reads this stuff anyway?
    I believe you might have an opportunity here to go beyond the usual perfunctory boilerplate on this topic, and offer some innovative advice.

    At minimum, you could tell some tales
    about the common traps and pitfalls involved in gaining an accurate strategic understanding of one’s customer’s information needs. I’ve seen some way off-target doc set requirements/designs as a writer, and I’m sure you have too as a manager.

    I suspect the person with the biggest challenge – when it comes to determining customer needs – has got to be the manager of a doc group embedded within a development organization.
    I take it that’s your intended audience for this book, right?
    If so, I have found that the writers in an embedded group often know a lot about how the product works -
    which they pick up from their day-to-day environment, from the engineers.
    But they often don’t have good information about how customers actually use the product – about the customer environment.

    I’m inspired to make this comment by your new section of working with HR.
    I’d also like to see you stress the importance of the doc group’s establishing both formal and informal relationships with customer support as well.

    I don’t know whether this topic belongs in Section 3.2 or in Section 5.3. – Working with the rest of the project. But here are a couple of cautionary tales to give you a sense of what I’m advocating to you.

    - When I joined one big BTL project as a writer,
    one of my subject matter experts was an engineer who split his time between the development organization and customer sites, doing installs. Through him, I learned that the project’s customer considered the existing documentation useless, because it made incorrect assumptions about the technical sophistication of its audience. I passed this info on to my doc manager (another new hire at the time). In turn, my manager worked with a manager in customer support to wrangle a week’s visit at the customer site for me from the project manager. I returned with a notebook full of information about what sort of docs the customer really needed. The project ended up redesigning and rewriting the entire doc set, and throwing away about 18 month’s worth of documentation. Lesson learned: customer support can be doc’s best friend, strategically.

    - Thanks to some scheduling fluke, I once attended a diversity awareness course (at another large corporation) with members of a customer support organization I hadn’t met before. It turned out we both supported the same product. More importantly, it also turned out their organization had developed a formal list of the top ten problems customers were having with the product – eight of which were directly related to deficiencies in the product documentation! But no one in customer support had ever said a word about this to the doc group. This wasn’t surprising to me. The parent company seemed to function as a collection of autonomous fiefdoms, and the two organizations – support and doc – were not accustomed to talking with one another. Lesson learned: #1 something about the lack of organizational diversity awareness in this particular company #2 the doc group’s failure to build a working relationship with customer support was a missed opportunity.

Comments are closed.