Words and Software

Technical writing/user assistance in Microsoft.Azure Intelligent Systems Service (ISS). (old: Data Protection Manager and Operations Manager)

Words and Software

  • Update or rewrite: how do you decide?

    This is a common scenario for technical writers: there is existing content, let's say for V1 of a product, and the same content needs to be provided for V2. Do you limit your work to making changes to the existing content for technical accuracy with V2? Or do you start with a blank slate and design a new doc, generously copying content from the old where applicable?

    Here are some of the issues I consider when making that call. The first two are fairly cut-and-dried, but after that it's more subjective.

    • How much is the product changing?  Is the next version of the product going to be so fundamentally different that very little of the old content is relevant or accurate? If yes, then you don't have much of a choice - start fresh, and take advantage of what's already written where you can. Most product versions aren't so dramatic or drastic though.
    • How much time do you have? If there isn't enough time in the schedule to do a new document, then you update the old one. Even if the old doc really needs a rework. You don't want release delayed because the documentation isn't done or incomplete/missing documentation at release. When the next version just has incremental changes and a handful of new features, and you have plenty of time for documentation, then you go to the next question.
    • Is there any feedback or customer data on the existing content? If you've only heard from customers that they love the existing doc, it doesn't mean that you shouldn't evaluate the doc for possible reorganization or structural changes or different approaches to topics, but it does indicate that you should carefully consider the potential impact of major changes on customer satisfaction.On the other hand, suppose customer feedback has been mixed or trending toward negative. This, then, is a great opportunity to start over with a new design that will aim to address any customer complaints or confusion. Sometimes you won't have any real data other than "nobody has complained about it." Then you go to the next question.
    • Can you make it better? Different is easy; better can be challenging. (How do you measure, for example?) Are you making changes to mark your turf or to improve the customers' experiences? Can you articulate why you believe the changes are a good idea and what you expect the changes to accomplish?

    Even when (1) the product isn't changing that much, and (2) you have plenty of time, and (3) there's really no feedback or data, and (4) you have definite ideas for improvement -- you still want to consider whether reworking this doc (rather than just updating) is the most important thing you could be doing with the time you have.

  • On to a new product: Windows Embedded

    I won't be writing any more about System Center 2012 - Operations Manager. After several years on the Operations Manager content team, and Data Protection Manager before that, I've moved to a new (to me) product team: Windows Embedded. Specifically, Device Manager (which extends Configuration Manager, so I guess I didn't really move too far away from System Center, eh?)

    The job description for my new position included a link to a video that interested me. It had never occurred to me that all the gadgets I take for granted had an operating system - I was so desktop/server-centric. "World of Windows Embedded" really piqued my interest and I'm excited to start learning a new product.

     

  • Changes to OpsMgr docs (System Center 2012) in Dec 2011

    If you follow us on Twitter (@opsmandoc), you'll be hearing about updated documentation for the Release Candidate being available later this week. Both TechNet and the downloadable docs will be refreshed. The following are the significant changes you can expect, in addition to added links and minor language fixes:

    • The Authoring Guide adds a new topic, "Diagnostics and Recoveries".
    • "What's New" adds an introduction to using Orchestrator in place of connectors.
    • Supported Configurations:
      • Adds the requirement of .NET Framework 4 if a gateway server manages UNIX/Linux computers or network devices.
      • Adds the requirement to install the web console to view Application Performance Monitoring event details.
    • The Deployment Guide:
      • Clarifies the order to install a management server and the web console on the same computer.
      • Adds notes in regards to existing AVIcode 5.7 agents.
      • Adds a procedure for assigning UNIX/Linux agents to a resource pool.
    • The Operations Guide:
      • Adds more tasks to the "Quick Reference".
      • Adds the NOAPM parameter to the instructions for installing an agent from the command line.
      • Adds note for Solaris UTF-8 support.
      • Adds instructions on using a VLAN tag for network monitoring.
      • Adds instructions for changing the default session limit for the web console.
      • Adds instructions for using scripts to configure the Operations Manager Web Part on SharePoint
      • New topics
        • Control Access by Using the Health Service Lockdown Tool
        • Operations Manager Reports Library
        • How to View Group Members, State, and Diagram
        • Connecting Management Groups
        • Using Operations Manager Shell
        • How and When to Clear the Cache
        • Recommendations for Daily, Weekly, and Monthly Operations Manager Tasks
  • OpsMgr 2012 release candidate docs: what's different

    Hope you all heard that the release candidate of Operations Manager 2012 is now available for download. The RC documentation is available on that download page and has also been updated on TechNet. So, as far as the documentation goes, what's changed?

    • What's New has been reorganized, with some art added, including an upgrade diagram and links to more detailed diagrams. Be sure to notice that the steps in the detailed diagrams each link to the corresponding content.
    • Key Concepts has been moved from the Operations Guide to the Getting Started section. In beta, it was basically a stub topic with a few paragraphs, but for RC more of the content has been filled in and it also has art added.
    • The release notes and Supported Configurations have been updated.
    • Sections of the Deployment Guide have been expanded since beta, such as single-server and distributed deployments. Disaster recovery has been added to the "Backup and Disaster Recovery" section, and also a number of procedures for "Making Changes to an Operations Manager Environment".
    • The Operations Guide has expanded content in a number of sections. "Application Monitoring Operator" has been added to the user roles. There is added information for UNIX/Linux credentials and for Run As account distribution. Information has been added to "Network Devices Supported for Discovery", which also links to Network Devices with Extended Monitoring Capability spreadsheet. The section on .NET Application Monitoring is also expanded.
    • Last but not least, the Authoring Guide and Cmdlet help are added to the library.
    • You also might notice a single topic for Report Authoring -- the Report Authoring Guide for Operations Manager 2007 R2 was just recently rewritten, and (other than the product name) the information is still applicable, so please continue to use the R2 guide for creating reports.    

    There is still a lot of content to add - you can see a number of placeholders in the Operations Guide, for example, and we have the entire planning & design section of the Deployment Guide to add. We plan to refresh the TechNet library on a monthly basis to add the new content as it's written. The tentative target for the next refresh is 15 Dec -- follow us on Twitter (@opsmandoc) to be sure to get all announcements.

  • Which management pack to save a group in

    The title of this post is the issue I'm trying to write about in Operations Manager 2012 Help. The more I dug into it, the more complicated it became. Not being a management pack author, I had never thought too much about references and what that means to things you might do in the Operations console, such as set an override or create a group.

    Anyway, the following is what I came up with for the basic guidance to an admin (not an MP developer):

     When you create a group, you save it to an unsealed management pack. However, an element in an unsealed management pack, such as a group, cannot reference an element in a different unsealed management pack, such as an override or a view. If you are going to use a group to target an override or scope a view, you must either save the group to the same unsealed management pack as the override or view, or you must seal the management pack that contains the group.

    If you save the group to the same unsealed management pack as the override or view, you can only use that group for overrides and views that are also contained in that unsealed management pack.

    If you seal the management pack that contains the group, you can reference that group from other unsealed management packs. However, you cannot easily change any group settings in the sealed management pack or add new groups to the sealed management pack.

    Before you create any groups in Operations Manager 2012, you should plan what groups you will need, the purpose each group will serve, and how to save the group in a manner that will allow it to be used for its intended purpose.

     

  • Operations Manager: what do you need to know to use it?

    This is actually an open question to you all. :)

    It's common for us to say our audience is the IT pro. But "IT pro" is a lazy shortcut to refer to a wide variety of people and positions. Does every IT pro know how to configure and manage permissions for SQL Server databases? Not necessarily, but the IT pro who uses Operations Manager should. So rather than just relying on the amorphous "IT pro" label, I think we should provide a list or overview of the skills and knowledge you need to successfully install and use Operations Manager.

    Think about when you first started using Operations Manager -- what did you need to know about SQL Server, IIS, Windows Server, Active Directory, DNS, PowerShell...? About anything? If you were going to hire someone to set up and run Operations Manager in your environment, what skills and knowledge would you expect them to have? Please click "Email Blog Author" over there on the right and let me know your thoughts!

    Edited to add: Just to clarify, I'm looking for the expertise with other products and technologies that you need before getting started with Operations Manager.

     

  • Operations Manager 2012 Beta released!

    The past few months have been all about the Operations Manager 2012 beta release, which, of course, I couldn't blog about while it was still in development. Now it's live, w00t!

    The documentation is available on the download site, but we also put it on our TechNet library-- Quick Start, Deployment Guide, Operations Guide, and Supported Configurations. The Quick Start is complete for beta, giving you a set of procedures to try out Operations Manager starting with a clean stand-alone install. The other documents are works in progress -- there will be a lot more content in them by the next release.

    And something new...flow diagrams for upgrading an Operations Manager 2007 management group. Interesting viewing, even if you're not upgrading any time soon.

    Check them out and let us know what you think. (There's an email link to the writers' team at the bottom of the flow chart. Actually, that email link is at the bottom of every page in our documentation set online for beta - we really do want to hear from you.)

    What else do you do with Operations Manager that you think this type of diagram would help you with?

    (edited to add tags)

  • Need volunteers: Operations Manager documentation survey

    Do you use Operations Manager? Would you be willing to complete a short email survey about operations documentation? If so, please send email to momdocs@microsoft.com.

    More details: The survey will be sent out approximately 21 March. We will use your responses to help us make decisions about organization and terminology so that the Operations Guide for the next version of OpsMgr will be easier to use. There won't be any information about the next version in the survey, so a non-disclosure agreement (NDA) is not necessary. We hope to get input from OpsMgr novices, experts, and everyone in between.

    edited to add: We'll ask that you reply to the survey by 1 April, so that will allow plenty of time for those who are busy the week of the 21st with MMS

  • "Back" not working on browser

    Some sort of "widget" is taking over all sorts of web sites, it seems. A few weeks ago, I noticed that some web pages wouldn't allow "Back" to work on my browser. When I hit the down button for back, there'd be a "widget.pulsemgr.com..." address between my search results and the page I'd gone to.

    Lately, I'm encountering that "widget" on more and more sites. Multiple widgets on some -- 3 or 4 between search results and the actual page. Since it finally became too annoying to overlook, I added the widget.pulsemgr.com address to my restricted site (Tools -> Internet Options -> Security tab).

    Now "Back" works properly again, I'm content.

  • Which user role(s) can perform this task?

    The content team is busily ramping up on doc plans for the next version of Operations Manager. (And I'll be very careful not to reveal anything about product changes, features, etc.) I'll be owning the operations content, so I'm working on new outlines and identifying current gaps.

    As I was going through the current content, it seemed like we mention user roles in a few places but don't really integrate them in the rest of the content. I'm thinking for v.Next, I should add which user roles can do something for every task/procedure. So, if I'm a Read-Only Operator looking at the operator's guide, I can immediately see whether I can do this thing I'm looking up or not.

    I don't know yet whether to include it at the beginning of each topic ("this information applies to the Operator user role"), at the end, preceding each procedure...somewhere consistent, definitely.

    What do you think, would user roles be a useful addition to relevant topics? Or are user roles easy enough to understand that it isn't necessary?

  • Would you use an Operations chm for SCOM?

    Currently, we post all of our Operations Manager documentation for download in doc format, and also post it on TechNet. And lately I've been thinking about whether we should also post .chms for download.

    I know .chm is a rather old-fashioned format, but personally I like it. I like the left nav for browsing, I prefer the .chm search to Word's, and unless it's a long narrative, I find it easier to read. I'm more comfortable following internal links in a .chm than a .doc because it's easier to find my way back to where I was. I also like the freedom of the offline experience (that's in comparison to TechNet rather than .doc format).

    For operations, Operations Manager has a User's Guide and an Administrator's Guide. If a .chm version of each of those guides was offered for download, would you download it? Would you find it useful?

    I haven't worked out all of the how-to details yet, but with a local .chm, you can create a console task to open the .chm from inside the Operations console. Is that something you would be interested in?

    If you are in favor of .chms of our operations content, what other content would be more useful to you in .chm format?

    Leave a comment or email momdocs@microsoft.com!

  • Office Word 2010 and product/company knowledge template

    If you write product knowledge or company knowledge for management packs, you'll be glad to hear that Microsoft Office 2010 (specifically Word) is supported for the knowledge template. Only the 32-bit version, however; the 64-bit version of Word 2010 won't work with the template. The software requirements for company knowledge and product knowledge are being updated this week.

  • Exchange 2007 MP product knowledge

    The Exchange management packs send you to the product knowledge articles online, rather than including the knowledge article in the management pack itself. When you view a knowledge article for the Exchange 2007 Management Pack, you might be confused to see references to "MOM Rule Path" and "MOM Rule Name". These are knowledge articles that apply to both Microsoft Operations Manager (MOM) 2005 and System Center Operations Manager 2007. The Explanation and User Action sections should give you the information you need to resolve the issue, whether you're using MOM or Operations Manager.

  • Change to Management Pack Guide library

    Old: When a guide couldn't be published in its entirety in the management pack guide library on TechNet, the page for that guide directed you to the Management Pack Catalog.

    New: Coming this week, the page for a guide that is only available by download will link directly to the download page for that specific management pack.

    Hopefully this small improvement will save you the time of searching through the catalog for the management pack guide that you want. The library pages should be updated by Thursday (4/22/10).

  • Operator Basics: getting started with Operations Manager

    I finally get to announce that the Operator Basics SuperFlow for Operations Manager 2007 is available for download!

    Superflow, you wonder? Configuration Manager pioneered this format for delivering information. It provides a complete set of content, which can include videos and animations and interactivity, in a single package.

    The Operator Basics SuperFlow is intended for front-line operators who are new to Operations Manager and, when they look at all of the content on TechNet, think "where the heck do I start?"

    It's also useful if you run a shop that needs getting-started training materials for operators. One of the sections in this SuperFlow enables you to add your own content (in an .rtf format) to the package, which makes it easy for you to include local resources, policies, etc.

  • Operations Manager 2007 SP1 Management Pack updated

    An updated download of the Operations Manager 2007 SP1 Management Pack is available. The management pack for Operations Manager hasn't changed, but the package now includes an updated version of the Operational Data Reporting (ODR) Management Pack, which is installed with Operations Manager.

    Here are some the changes you'll see in the ODR MP:

  • The instance space report is now available on both Operations Manager 2007 SP1 and Operations Manager 2007 R2. Previously, this report was only available on Operations Manager 2007 R2.

  • The Management Packs report is updated so that the list of overrides also shows disabled rules and monitors.

  • A new report is added which shows the number of alerts per day generated by a particular rule or monitor.

  • Report descriptions were updated.

  • The Most Common Alerts report was updated to show the top 50 alerts instead of the top 25.
  • Operations Manager capacity planning

    Need some help planning your Operations Manager deployment? Check out the Operations Manager 2007 R2 Sizing Helper.

    The Operations Manager 2007 R2 Sizing Helper is an interactive Excel document designed to assist you with planning & sizing deployments of Operations Manager 2007 R2. It helps you plan the correct amount of infrastructure needed for a new OpsMgr R2 deployment, removing the uncertainties in making IT hardware purchases and optimizes cost. A typical recommendation will include the recommended hardware specification for each server role, topology diagram and storage requirement. The Operations Manager Sizing Helper is most useful when used with the Operations Manager 2007 R2 Design Guide (http://go.microsoft.com/fwlink/?LinkId=184377).

    The Sizing Helper was previously available through the System Center Operations Manager blog.

  • SQL MP guide updated

    I recently mentioned that we're changing how MP guides are released. The SQL Server Management Pack is the first to take advantage of the new system by making an update to the guide without repackaging the management pack .msi. Just download the .doc to get the latest guide - no need to download the .msi again (the MP hasn't changed). 

  • Visual Basic 2008 Express: Build a Program Now! sample files

    I decided to try to learn Visual Basic, so I picked up a book that looked promising: Microsoft Visual Basic 2008 Express Edition: Build a Program Now! I've been working through the chapters. In chapter 6, (adding a splash screen) it instructs you to replace the default icon with one from the companion files for the book.

    Time to go out and install them, so I flip back to the start of the book to the instructions. The book says to download them from http://www.microsoft.com/mspress/companion/9780735625419. Dead link. I did a search, it pointed me to that same URL. Fortunately, search also surfaced a discussion thread where someone else was hunting for this download and someone else replied "Look here and click the "Companion Content" tab!".

    So I thought I'd share.

  • MP guides to be separate download

    A sharp-eyed blogger (Pete Zerger) noticed a change in our management pack download pages. Here's what's going on:

    • Guides will be available as a separate download, on the same download page as their respective management packs.
    • For a short period of time, guides will still be in the .msi as well. Eventually, the guide will only be available as a separate download and won't be in the .msi package at all. (Why not immediately? It's going to take time for us to communicate this to every team that does a management pack, and we don't want to delay any releases by making a team repackage the .msi just because it still has a guide in it.)

    One benefit that we hope to achieve with this is to make it easier and faster for teams to make changes and fixes to the documentation. In our old method, a guide fix meant completely repackaging and retesting the .msi. Now, the .msi won't change so updating the guide will be much less effort.

  • Writing good technical documentation, part 3

    (Part 2)

    (Part 1)

    Nathan Bransford, a literary agent, blogged about his difficulty in getting writers to paste their original query into their partial manuscript. Here are the instructions he sends them:

    "Thank you for your recent note. Would you mind sending me the first 30 pages in a Word attachment? Please paste your below e-mail in the first page of the Word document. I look forward to getting to know your work."

    He estimates that he has about a 75% success rate (not bad!) but would like to improve it. Enthusiastic commenters offer numerous suggestions for rewording the instructions, and at least one of them mentions that it's like technical writing, which of course caught my attention.

    Technical writing is full of procedures (or instructions, if you prefer that term). From my perspective working on server products here at Microsoft, the main purpose for the documentation is to help you do something with our product, and quite often the means is a "how to" procedure.

    How can you go wrong with procedures? Well, the obvious answers are missing steps, having the wrong steps, using jargon that doesn't match what the user sees, and so forth. But a procedure can be methodical and precise and accurate, yet still not meet the user's need, if it's missing the "why".

    I'll use one of my own topics (where I failed on "why") as an example:

    Vendors might periodically update a management pack. When a management pack is updated, the version number incrementally increases. You can check the version number of imported management packs in Operations Manager 2007.

    To check the version of a management pack...(procedure follows)

    Version number can change, you can check it -- but why do you care whether the version number changed or not? What good is that knowledge to you? I haven't given you any idea when you would want to check it or how you should know to check it or what to do with the version number once you have checked it. All of that belongs in "why". (Meanwhile, I've sent myself a note to update that topic.)

    Awhile back, in one of those team-building type workshops companies love, we did an exercise where one person had all of the instructions and the other team members had pieces of information. The "leader" had a goal to accomplish that required coordinating all of those pieces of information. Our team was the first to finish, but every member stated that it would have been a lot easier if they had been told what the goal was and why they were doing certain things. (That stuck with me all this time because I was the person who had the goal and failed to share the "why" with the team.)

    An adequate procedure tells you "how to". A good procedure tells you "when" and "why" and "then what". Which brings me back to Nathan's post. When I read it, my first thought was that he should tell the writers that he reads their submissions in his Kindle and that is why he needs the query in the partial -- if I understand the why, I'm more inclined to cooperate. Since several commenters made the same suggestion, I refrained from adding to the thread there and hijacked the thought into a post here instead.

  • R2: check for MP updates

    There hasn't been an easy way to check for management pack updates in Operations Manager 2007 until the R2 release. Once you're running R2, you can use the Import Management Packs wizard to determine if any of the MPs you are running have had an update released. Just follow the instructions on How to Import a Management Pack, and in step 4, be sure to select Updates available for management packs that are already imported on this computer.

  • Submit questions for the Operator's Manual

    There are two ways to approach content on using the Operations console and Web console for Operations Manager:

    1. Explain what information is available in each section of the consoles.
    2. Take examples of information that an operator would want to locate, and tell them how to find it in the consoles.

    I've decided to do it both ways, in a guide that I'm putting together for new Ops Mgr operators. Here are a few questions for #2 that I harvested from an email discussion:

    • I have added a Management Group in the console and I also added few computers, how do I know if these computers belong to the management group that I added?
    • How do I know if a management pack is applied or connected to the servers that I added in the console?

    What other questions might an operator want to answer in the console? Submit your suggestions to jdecker AT microsoft DOT com!

  • Is your IE8 slow to open a new tab?

    Whenever I would open a new tab in IE8, whether by control-clicking a link or simply clicking the New Tab tab, everything would go dead for a good 10-20 seconds until IE8would finally show a new tab and then begin trying to open something in it. (Yeah, it always feels like longer.) It finally began bothering me enough that I started searching for a fix.

    The first suggestion I came upon had to do with the restricted sites list. Checked -- didn't have one.

    The second suggestion was to run regsvr32 actxprxy.dll. Tried it -- no improvement.

    (That doesn't mean that either of those fixes are wrong, it just means I have some other issue.)

    I finally came across the fix that I needed in the comments to a post criticizing that second fix above. Add-ons! Clicked Tools -> Manage Add-Ons and there it was: ZuneIEPlugin.ZuneBHO, with a load time of 7.62 seconds. I disabled it and voilà! My tabs work nicely again.

    If you too suffer from sluggish tabs, try those three suggestions and hopefully one of them will work for you as well!

  • MP Guide for Operations Manager 2007 R2

    The management pack guide for the Operations Manager Management Pack (Operations Manager 2007 R2 only) is available for download.

    Usually, the guide is in the download with the management pack, but since the new Operations Manager Management Pack is included in the R2 product, we published the guide separately. We'll also be adding a link to the guide download to the System Center Pack Catalog, to make it easier for customer to find.

    Note that if you are not running Ops Mgr R2, you do not want this guide!