Customer Reviews

Managing Writers: A Real World Guide To Managing Technical Documentation

5 star:		(4)
4 star:		(5)
3 star:		(0)
2 star:		(0)
1 star:		(0)

 

 

Managing Writers is clearly organized and a fast read. It often reads like a reference guide, a book you could keep on your bookshelf for years to come.

It is a reference guide in my view, because you can go straight to the table of contents and pick from the list of topics. Want to get your arms around people? Refer to many chapters on Managing People. Need to know insider information on projects before it spirals out of control? Stop the spin machine and go to the pages about Managing Projects. Wondering if the latest alphabet-based tossed salad of acronyms will actually solve your user's information problems? Hightail it to the Managing Technology chapters. Each of his chapters offers the depth and detail you'd need when faced with a situation you hadn't seen before. For example, if you're new to Localization, the information offered will help you ask the right questions and help you get started while avoiding headaches and "time sinks."

As I read through this book, I felt like I was having a nice long lunch with one of my favorite managers. It's sprinkled with stories and phrases like "gold-plated Cadillac." I enjoyed reading about his path to technical publications. It seems many people are eager to leave tech pubs once they start in it. Richard didn't know much about tech pubs, and wondered if he was leaving the world of technology, but accepted a position anyway. He was willing to learn and stay with it. And stay with it he did, for many years beyond the first two he promised to the hiring manager.

Whether you're already managing a handful of writers or just starting out, or if you're hoping to move towards management in technical publications, I think you'll find this book helpful. Even an experienced tech pubs manager will enjoy hearing another's perspective and will find many familiar themes that match their own companies and product documentation.

It's all there in the subtitle: A Real World Guide to Managing Technical
Documentation. This book gives practical advice about how to advance your
team's interests, for instance, and is also meant for those who aspire
to be managers or just want to see how things look from the manager's
point of view. Plus, it's a real page turner, far from the heavy,
research-oriented books I've come across.

Many variables ultimately contribute to the effectiveness of a manager; I believe one of the most important is the availability of a strong mentor. Many technical writers do not have access to a strong documentation manager, and even fewer managers have access to a mentor with documentation management experience. If your organization is fortunate to have one, use that opportunity to learn as much as you can from that individual. Whether or not you have access to a good mentor, there is much you can learn from reading Managing Writers by Richard L. Hamilton.

[...]

_Managing Technical Writers, A Real World Guide to Managing Technical Documentation_ by Richard Hamilton is a well-written and brief but comprehensive overview of the challenges any tech writing group faces and the most effective strategies for overcoming them. Although the title suggests that the book is for managers, in fact, it is valuable for all members of the field from students in tech writing programs (or Liberal Arts majors tricking their way into the field) to managers and managers of managers who supervise writers. I would say that it is valuable to writers who are individual contributors not just in spite of the fact that it is written for managers but often because it is written for managers helps the writer understand the manager's point of view.

If you have been in the field for a while, much of this book will seem like common sense to you. I see that as a very good thing because it inspires confidence when I come across sections addressing situations I have not yet encountered.

I would recommend reading the book once cover to cover and later rereading chapters when you face specific situations. I suspect that the book is most relevant to writers in the hardware and software fields. For technical writers in other fields, such as medical technical writing, I suspect that much still applies, but the examples all come from hardware and software scenarios.

I had to think pretty hard to come up with topics that were not covered. One that I finally came up with was the relationship between a technical writing group and marketing. I believe this subject deserves several pages to explore fully. Often the technical writer is put in an awkward position between the demands of product marketing's story about what the product is and does and product development's story about what the product actually is and actually does. In my experience, attempting to satisfy product marketing in this situation leads to frustration on the part of the writer and ultimately to unusable documentation. Of course, I can also think of positive examples where a healthy relationship between product marketing and tech pubs has vastly improved the quality of the documentation.

A few words are also in order about the relationship between the test group and tech pubs. Often these two groups benefit from banding together to protect themselves against the crunch of slipping development milestones and a non-slipping final release date. When development slips milestones, not enough time remains for testing or writing. If test and pubs do not stand together, they will find themselves competing for developer time to finish testing and documentation, both of which will suffer.

The chapter on internationalization and localization felt light, but a more in depth treatment was probably beyond the scope of the book. I think in this case a bibliography of some recent books on the subject would help. In the context of the discussion of the benefits of XML, it is worth mentioning that you can use attributes to indicate what content should not be translated. By removing the content of code listings, method names, and other obviously untranslatable content you can reduce the word count that you send to the translation vendor and so reduce the cost of the project. See Jirka Kosek's blog entry "DocBook, translations and ITS" (at xmlguru.cz/2006/03/docbook-and-its) for a discussion of this in the context of DocBook.

In the chapter introducing semantic markup, I would have used something other than the <emphasis> element in the examples since <emphasis> is only slightly more semantic than or . I think something like like <filename><replaceable>path_to</replaceable>/foo/bar</filename> or <database class="table">customer</database> would do a better job of getting the idea of semantics across. In the <database> example, you could discuss the opportunity of automatically generating index terms or automatically hyperlinking to a reference section in a data dictionary.

The book never mentions one of my favorite benefits of XML: With an XML-based tool chain it is much easier to pull in content programmatically. When you are documenting software, you often find yourself writing a reference guide of some kind where you are documenting objects that already exist in a structured format in the code. In the case of a Java API, you can use Javadoc to automate the process. However, you are documenting a database schema, the details of a chip design, a Web service, or objects specific to a particular piece of software. Since these objects are used in some software process already, they must exist in a structured format which can be converted programmatically to XML and in some cases the native format is already XML. In these cases, and XML-based tool chain offers opportunities for automation that do not exist in DTP-based tools. Removing manual cut-and-pasting makes the tech writer's job less tedious and removes a common vector for errors and inaccuracies.

Chapter 20 struck me as somewhat dismissive of using source control systems like svn in place of a true content management systems in XML-based tool chains. In my experience, for a writing group in a software shop, there are many benefits for tech pubs in piggy-backing off of development and using their source control and build systems for content management and publishing. The investment in and maintenance of the systems is a sunk cost that the development group has already made. Using development's system frees up resources for improving other aspects of the tool chain such as the publishing system and editing environment. Using development's build infrastructure makes it easier to integrate with development's builds. By sharing development's build infrastructure, writers will be drawn closer to development, have more visibility into dev processes, and better understand the world that developers inhabit.

Chapter 21 on avoiding common pitfalls makes an important point: "...your users will resist change where the total perceived benefit to them is less than the total perceived pain of adoption." This is true of any change but is especially important to keep in mind when adopting an XML-based system. Many of the benefits of such a system accrue to the company rather than the individual writer. However, it doesn't have to be that way. Semantic markup can enable features that make the day-to-day life of the writer easier. For example, using some editors like oXygen, XMetaL, and Serna support smart spell checking so that the spell checker skips words in certain element like programlisting, code, and so on. The point is that it is important to invest in convenience features for the writers when setting up your tool chain.

My hope is that Managing Technical Writers will be widely read by tech writing managers, tech writers, and students in tech writing programs. I also hope that every five years or so it is updated to take into account new trends in technology and the field. Much of the book is not dependent on specific technological details, but occasionally updating it will keep things fresh.

This slender volume presents a useful framework to manage technical writing projects. We especially like the 3 dimensions to consider when managing a project: time, content, resources. He does not advocate for any specific hardware or software, mainly presents a theoretical framework with many things to consider.

Contrary to what the the main title of this book might suggest, it is also an interesting read for technical communicators.

A few chapters that are particularly useful for TCs include:
"Hiring", which gives insight into the reasons for hiring or not hiring someone, invaluable info if you are looking for a job;
"Measurement and metrics", useful for TCs who are confronted by a page-count-per-day metric, suggesting what could be measured instead;
"Project planning", how to deal with unreasonable schedules, and how to help engineering solve their documentation problems while solving your own;
"Localization"; and
"Managing technology", which describes how to select tools that support the way you (want to) work, instead of the other way around.

Overall, the book gives some good suggestions how to increase your credibility and influence as a TC/TC department, and how to create better relationships with other departments. In the end, this will probably make your job a lot easier, and fun.

This is one of the best guides I have read on the hard-to-find topic of managing writers. There are many good texts on managing the writing process, but very few on working with the creative people who do the writing. This fills a needed niche.

I've been a documentation manager for five years (and a writer for ten years before that) and found Hamilton's book to be a useful reminder of the things I need to be concerned about. While I still lean on Hackos' books for detailed, theoretical information, Hamilton's book is a handy and practical reference. It's concise, well written, thoughtful, and extremely practical. This book has found a place on my bookshelf and I believe that any doc manager can benefit from Hamilton's experience.

Richard Hamilton's a must read for anybody who is managing or aspires to manage a technical communications book. Not only does it deal with some of the people issues involved but it gives a realistic view of where tech. comm. exists in a product development environment. Even managers who currently are not managing a tech. comm. department should read it to get a better understanding of how they can change some attitudes and processes to give the product a better chance of success with their customers as the information about the product is as critical to success as the product functionality.

Written in an easy-to-read style with a few engaging stories to drive the point home, Richard Hamilton's Managing Writers is definitely the best book on the subject and will be a great point of reference for years to come.