This time I look at two books that have little in common. One provides a nuts and bolts account of how to approach a difficult real world problem. The other looks at the kinds of fanciful, artificial problems that interviewers at some high tech companies -- and their imitators -- pose to job applicants.
Single Sourcing -- Building Modular Documentation by Kurt Ament (William Andrew, Norwich NY, 2003, 246pp, www.williamandrew.com, ISBN 0-8155-1491-3, $33.95)
Single sourcing is a way to produce documentation so that you only have to write the meat of it once. You create a collection of modules, each of which says one thing well. Then you use those modules to publish the same information in many forms -- print and online, reference guides and training materials, English and Japanese, and so forth. At least, that's the theory. The devil is in the details.
Kurt Ament is an information architect. He has used XML, and its predecessor, SGML, to produce single sourced documentation for Hewlett-Packard, Hughes Aircraft, Xerox, and other large companies. He has distilled the experience he gained from these jobs into a clear and concise guide to approaching large documentation projects. Others have written thick volumes on aspects of this problem. Ament does a better job in a lot less space by focusing on the key issues:
- structured information
- teamwork
- modular writing
He addresses these issues independently of the underlying technology, but his examples refer to popular tools.
There are many systematic techniques for producing structured information. Ament settles on a fairly simple one. If you are converting old documents into structured form, you can start by analyzing the information in the old documents. Otherwise you can start from scratch. In either case, Ament's taxonomy has two levels: primary modules and secondary modules. The primary modules are topics, processes, procedures, definition lists, and similar entities. The secondary modules are examples, figures, tables, notes, itemized lists, and entities of that sort. Ament's method calls for identifying, labeling, organizing, and producing these modules.
One step in producing structured information is to integrate the secondary modules into primary modules. Ament provides guidelines for this. Some types of secondary modules are inappropriate for some types of primary modules. Ament is particularly hard on tables. He wants to keep them out of most kinds of primary modules. In general, he finds them hard to work with when producing output in more than one format.
Another step is arranging modules into hierarchical documents. Ament recognizes that using a hierarchical structure helps writers ensure that their documents are comprehensive and coherent. Unfortunately, readers, especially online readers, have difficulty perceiving and navigating within a hierarchy. Ament recommends flattening the natural hierarchies of documents to make them more usable. This is much easier said than done, and Ament does not give much practical advice in this area.
Another important step is to design the linkages that underlie the navigational aids in the target output. These linkages take the form of tables of contents, indexes, and inter-module references. Doing this carefully is important for all documents, but especially those intended to be viewed online. Ament gives guidelines for these tasks, but he cannot teach you how to perform them. I understand that he has written a separate book on indexing, but I have not seen it.
Ament's process is ongoing. After you build and test the documents that embody your structured information, you look at the lessons learned and adjust your process. This is an important step in all projects, but it is especially important in single sourcing large document sets. Here success depends on having a process within which individual writers can work together to speak with a single voice.
The success of single sourcing projects depends heavily on teamwork. Individual writers must accommodate their personal writing styles to match the team voice. Ament recommends that team members develop writing guidelines based on what works in actual projects and adopt these guidelines by unanimous consent. This limits the style guide to rules that everybody agrees to. People have difficulty following rules they don't believe in. If team members don't follow team rules, the team falls apart.
Ament suggests a division of labor within teams. He wants to centralize information architecture and distribute information development. These functions tend to have competing objectives, and the people who perform these functions have disparate viewpoints. As a result, Ament stresses the need for these groups to overcommunicate.
Ament devotes about half of this short book to what amounts to a sample style guide for a single sourcing team. The fact that he can write a style guide in 130 pages shows that he follows his own rules: he sticks to what works in actual projects, and he proposes rules that everybody is likely to agree with. This section is the heart of the book, because it addresses the difficult problems of writing modularly. Modular writing does not come naturally to most writers, but without it you cannot produce successful single sourcing projects.
Ament makes an interesting point: what works in print may not work online, but whatever works online usually works even better in print. Thus, his guidelines for modular writing come mostly from the needs and constraints of online documentation.
For a documentation department planning a single sourcing project, this book is pure gold. Ament writes clearly and concisely. He brings real world experience to the most difficult issues and offers practical advice for addressing them. If your success depends on producing usable product documentation in a variety of forms, you must read this book.
How Would You Move Mount Fuji? -- Microsoft's Cult of the Puzzle by William Poundstone (Little Brown, Boston MA, 2003, 290pp, ISBN 0-316-91916-0, $22.95)
William Poundstone is a well known science writer. He has produced a thought provoking and highly entertaining book. The book is thought provoking because it examines a widespread practice, the posing of tricky and artificial logic puzzles to job applicants. It is entertaining because it includes many representative puzzles and because it pokes fun at Microsoft.
I have no personal bias either against or in favor of the Microsoft Corporation. I use their software every day. I enjoy its benefits, but often curse its faults. I have never interviewed for a job with Microsoft, so I have no idea how true or fair anything in this book is. Nonetheless, I thoroughly enjoyed reading it.
Poundstone describes Microsoft job interviews as a gauntlet, akin to fraternity hazing. He includes accounts of several actual interviews -- each quite funny and each resulting in "no hire." Microsoft has many more job applicants than open positions. Their principal objective in interviewing is to disqualify anyone they're not completely sure about.
Part of the hazing is to confront applicants with questions like "Count in base negative 2," "If you could remove any of the fifty U.S. states, which would it be?" or "How would you move Mount Fuji?" Other questions, however, are logic puzzles like finding the underweight billiard ball with a minimum number of weighings or determining how to get the missionaries and the cannibals across the river. The justification for asking questions of this variety usually begins with "It stands to reason that . . ." and asserts a correlation between the ability to solve such puzzles and future success writing computer programs. The degree of correlation is known in the testing business as the validity of the test. Even under controlled conditions, standardized IQ tests have questionable validity as predictors of any sort of job success. Logic puzzles, in the chaotic environment of a job interview have no established validity at all.
Even though questions of this sort have little value in job interviews, they have become increasingly popular in a wide range of industries. Companies try to emulate Microsoft -- either out of a wish to achieve similar success or because more traditional hiring approaches have become completely ineffective. Legal considerations have made obtaining useful information -- especially negative information -- from personal references difficult. Candidates come in with well rehearsed answers to traditional questions like "What's your greatest fault?" or "Where do you see yourself five years from now?" A question about the probability of dying in a game of Russian roulette adds a little spice to the process -- at least until all potential applicants have rehearsed answers to that question too.
While I have little interest in job interviews, I found the book fascinating. I enjoyed the opportunity to think of plausible answers to the impossible/stupid questions and to work out the logic puzzles. My ten year old daughter got a big kick out of the questions too. We spent a whole afternoon discussing the problems and reading some of Poundstone's answers. Then she went off to tell her mother how to move Mount Fuji.
Poundstone provides answers to the questions he mentions in the book. He also puts forth a few general rules for addressing this type of question. He frames the discussion in terms of how you should interact with the interviewer.
Given the widespread nature of this interviewing technique, if you are looking for work, you should definitely read this book.
