The Unsung Heroes - Technical Documentation Professionals

The Unsung Heroes - Technical Documentation Professionals

By CWNP On 12/01/2008 - 16 Comments

One of the things that holds Enterprise Wi-Fi companies back is a lack of documented deployment strategies - often called Design Guides or Best Practices documents.  Cisco no doubt knows this because their design guides are released almost as fast as their equipment, and they keep them up-to-date.  These are great documents if you can find the time to read and digest up to 360 pages of detailed technical material per document (Enterprise Mobility, VoWLAN, & Security).  Aruba kinda/sorta has some of these types of documents, and they go by names like, 'Campus Wireless Networks Validated Reference Design' and 'Site Survey and Planning Pre-Deployment Guide.'  All combined, Aruba's guides make up enough documentation to get most of the job done.  Motorola has recently released their version, finally, and it's a Cisco-like 320 pages.  Sweet.  That's very good news for Moto VARs.

 

Now you have to ask yourself, 'Who the heck reads these things anyway?'  Most engineers use them as reference documents instead of treating them like a book to be read from cover-to-cover.  As reference docs, they're OK, but they typically hold more than just the technical information needed for deployment.  They almost always illustrate and vet the company's corporate mentality toward the technology.  One vendor will say, 'You have to do it this way!' while the other is saying, 'You must do it this other way!'  Those two ways could be opposites of course.  It's important to understand deployment 'philosophies.'  I've even seen where multiple documents from the same vendor will give two opposing kinds of advice on deployment of a given platform.  I think that stems from the authors not being on the same page about a particular technology and apparently QA is MIA.  We call that 'left-hand, right-hand', which is short for 'your left hand doesn't know what you're right hand is doing.'  

My advice: Read each major vendor's deployment/design guides cover-to-cover even if you don't deploy their solution.  It will give you great insight into that company, their solution, their 'twist' on things, and how it compares to the solution you're currently selling/installing/supporting.

One last thing before I get to the point: Configuration Guides.  These puppies are essential...for reference.  Without them, most engineers will just get stuck at some point.  They don't make good reading material, but when you need them, you REALLY need them.  It's more than essential that these guides be deadly accurate, thorough, and intuitive...yes, read, 'e-a-s-y to understand'.  There are so many configuration guides that have left out small details that require that the field engineer have to call support to get to the answer.  This also applies to release notes since they often contain new configuration information.  

Now, to the point of this article.  I want to send a shout-out to those unsung heroes of technical documentation that take the time to get it right.  We engineers appreciate you more than you'll ever know.  I still haven't figured out how you guys make those source documents (MS Word? InDesign?) into those way-cool eBooks (the ones with the expanding menu in the left pane) using Acrobat.  If someone wants to do something nice for yours-truly as a Christmas gift, show me how to do that. :)

Blog Disclaimer: The opinions expressed within these blog posts are solely the author’s and do not reflect the opinions and beliefs of the Certitrek, CWNP or its affiliates.