BRONZE PARTNER:
BRONZE PARTNER:
Industry News:
| |
| |
|
|
|
|
|
| A Day in the Life of a Technical Writer - What's In and What's Not |
|
|
|
By: Steven Kaczmarek
Posted On: 2/14/2008
~Steve Kaczmarek ¡V Content Publishing Manager, Configuration Manager 2007
Over the past several months, the writers and I have responded to several questions and other feedback about the Configuration Manager content. Often the real question in "why did you do that" or more frequently "why isn't that in the content" or even "is that Jeff Gilbert really such a high maintenance writer". So, I thought I'd periodically respond to your questions and feedback in an article I'll call "A Day in the Life of a Technical Writer". In this first article, rather than talk about just how high maintenance Jeff really is, I'll take the easier route and speak to how we set the boundaries as to what we include and do not include in the prescriptive guidance for Configuration Manager.
Let's start by taking a look at the volume of content we've produced for Configuration Manager from its release through the current betas of SP1 and R2. We've published well over 2 million words - from 8 writers! Given the industry standard of 3 pages a day per writer, that 2 million words represents a lot of hard work and long hours put in by the writing team. To enable you our customers to use the product successfully on a day-to-day basis, we have to make some choices about what we include in the content.
Early on in the documentation plan development, we decided not to include prescriptive guidance for products and technologies that Configuration Manager interfaced with or had dependencies on. We would rely on the pre-requisite that you needed to understand that product or technology, including getting whatever aspects of it necessary for Configuration Manager set up and installed. When Configuration Manager entered the picture, we would pick up with the specific requirements, settings, planning elements, and so on that would make you successful with Configuration Manager with respect to the other products or technologies. We also cannot document procedures and scenarios that havenot been tested by the Configuration Manager test team. We have a partnership with the development and test teams wherein they sign off on our content. By signing off, they essentially agree to support it. So, they won't sign off on anything that has not been tested.
What's he saying? Is this campaign double-speak? Not really :) Here's an example. Take PKI. We get a lot ¡V and I mean a LOT of feedback about not including steps for how to set up the PKI environment outside of Configuration Manager. We (Carol Bailey, to be specific) did a lot of research into setting up the PKI environment and whether we could reduce that to some general guidance for you. Well, PKI is a Windows Server technology, and implementing it is dependent on many factors in your network and server infrastructure. Since Windows Server had already documented how to implement PKI (for better or worse), we ask you to go to that source material first, implement PKI, and then come back to our documentation in which we tell you how to proceed in the Configuration Manager environment. Recall this from Carol's blog:
The step-by-step was never intended to be a complete solution for any native mode deployment. It was intended to help administrators with no or little PKI knowledge get a basic native mode site up and running in a test environment as a proof of concept. With this intended audience, its aim was to step through the easiest deployment possible using the fewest number of steps.
Another reason we choose not to re-document dependent technologies and products has to do with their supporting content. We have no control over the Windows Server documentation. If they decided to change functionality in the technology or update their content with additional guidance, we would have no way of knowing that. Our own content could become inaccurate or out-of-date, and that could result in an unpredictable experience for you. If you look closely - and I know you do - you see that we purposely follow this course for other technologies that Configuration Manager interfaces with, including WSUS and Network Access Protection.
We want to do right by our customers and it is hard when we have to make these decisions. Ultimately, though, we want to provide you with the best experience with Configuration Manager, even if that means giving you just enough information to get started. Sometimes that means you have to do some homework on other technologies before you come to our "class" :)
I hope this sheds some light on one aspect of our jobs. Please feel free to send me your questions and comments and suggestions for future installments of "A Day in the Life of a Technical Writer." Time now for that one-on-one meeting with Jeff.
|
|
|
|
|
|
