Creating product guidance

Creating product guidance

  • Comments 1
  • Likes

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.

 

 

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • In my last post, Creating Project Guidance , I talked about how we produce scenario-based documentation