TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Our new project here at work uses a lot of vendor equipment. We are writing new
customer docs for the overall system, but the customer will also receive a set
of the vendors' documentation to describe the nitty gritty of the individual
pieces of this new system (perhaps 20 manuals).
We writers have been asked to prepare a documentation roadmap, essentially a
table or master index that will help the customer find the information needed
without going into each vendor doc. So, for example, if you need
troubleshooting info on the VendorXYZ box, you look up Troubleshooting in the
roadmap table, look under XYZ, and find the chapter or subsection it's in.
Anyone done anything like this? Any good examples to point us to? We are
having trouble deciding what degree of detail we need in listing the topics
(e.g., Troubleshooting vs Troubleshooting the ABC Event vs ABC Event; Desktops
vs Desktop Configuration vs Configuring Your System).
Yes, the customer can simply open a vendor doc to its TOC or index, but I
suppose the thinking is that having a roadmap is less daunting than looking at a
bookshelf of various manuals, and it puts everything at one's fingertips.
Thanks for any advice.
Carl Gotlieb
gotliebc -at- agcs -dot- com
AG Communication Systems
Phoenix, AZ
