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.
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.
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.
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:
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?
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.
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.
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.
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)
Do you use Operations Manager? Would you be willing to complete a short email survey about operations documentation? If so, please send email to firstname.lastname@example.org.
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.
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.
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?
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 email@example.com!
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.
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.
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).
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.
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:
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.
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).
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.
A sharp-eyed blogger (Pete Zerger) noticed a change in our management pack download pages. Here's what's going on:
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.
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)
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.
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.
There are two ways to approach content on using the Operations console and Web console for Operations Manager:
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:
What other questions might an operator want to answer in the console? Submit your suggestions to jdecker AT microsoft DOT com!
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!
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!