Creating product guidance

Published Feb 14 2019 08:51 PM 55 Views
First published on TECHNET on Feb 07, 2009

Hi, I'm Jonobie Ford, and I'm the Content Publishing manager for Service Manager. That is, I manage the team that produces product documentation such as TechNet and Download center content, help, videos, etc. (We also do behind-the-scenes work on UI text and terminology, but today I’m focusing on the content authoring aspect.) I previously worked on the Operations Manager team, and prior to that worked for IBM in the Tivoli brand. I'd like to give you a quick behind-the-scenes view of how we write for the product.

Generally speaking, our writers are organized around large areas of the product and are focused on specific  scenarios. For example, we have writers whose dedicated areas are:

* Installation and initial configuration

* Operations (Administrative tasks)

* Operations (Analyst tasks)

* Reporting

* Backup and restore

* Security

* Performance

* Extensibility (Management pack authoring and Powershell)

* Extensibility (SDK)

Some writers cover multiple areas. You've met some of our writers on this blog already - John Downing writes security and installation information, and Bill Anderson writes performance and operations information.

Early in a development cycle, one of our priorities is to provide step-by-step guidance for the major product  scenarios. Once we get the majority of the step-by-step instructions created, we start creating the next layer – guidance about how to choose between different scenarios, etc. If you look at our Beta 1 documentation, you'll see that we have two documents that end with the characters "SxS". Following the Initial_Config_SxS document from beginning to end will get you an installation that is connected to AD and ConfigMgr and has basic notifications and templates configured. Following the SM_IncidentChgMgmt_SxS document will walk you through the basics of the Incident and Change Management process.

This approach means that although we don't document every single knob and field of the product, we provide a  recommended path through the software. We call this "scenario-based documentation”, because we're writing about the major scenarios in which the product is used, instead of focusing on feature-by-feature descriptions.  We're also trying something new this release that we're calling narrative-based documentation ; we'll talk more about that in a different post.

Version history
Last update:
‎Mar 11 2019 08:07 AM
Updated by: