When you create a component in a management pack, you have to provide a display name. You can also include a description and product knowledge. All three of those items are pretty much free-form, meaning you can put what you want in those fields (subject to character limitations, of course). That means that every MP developer has had to make decisions about when to use those fields and what to put in them.
That's just not a good use of a developer's time, and it also results in an inconsistent experience for customers using MPs from different developers. To help reduce that problem internally, we came up with guidelines for text in MPs: specifically, display names, descriptions, and product knowledge. One of our program managers suggested we provide similar guidance for developers and authors outside of Microsoft, so I cleaned it up (removed resources and links that are internal) and it's now available on OpsManJam: Guidelines for MP Text.
(edit: fixed typo)
Back when Operations Manager 2007 was released, the content team posted an online version of a Key Concepts Guide and a download version. When you look at our documentation download page for Ops Mgr 2007 R2, Key Concepts isn't listed. Where did it go?
When the product was new, we wanted to highlight Key Concepts to clarify the differences between MOM 2005 and Ops Mgr 2007. With R2, we're not really a "new" product anymore. The explanations of model-based design, service modeling, and health modeling are primarily of value to the authoring experience. So, when we reorganized the content library in the R2 release, the Key Concepts content was added to the Management Pack Authoring Guide.
P.S. The links to the original content (first paragraph) still pull up the original content, but notice that the left navigation pane fails to resolve to a table of contents. Whenever you hit TechNet content and the navigation pane goes generic, you know you've reached deprecated content.
Scott Hanselman has a suggestion for tech support -- a codeword that clues in the help desk that you kinda know what you're doing. I'm not sure fizzbin will catch on, but it's a nice dream...
Joel Spolsky has an excellent post on the role of the program manager. I work with program managers, so I read through it comparing his descriptions with the PMs I've known. Then I got to the part on functional specifications and my interest level jumped a few notches.
Because the spec is -- or can be -- one of the technical writer's best tools.
By coincidence, my manager recently asked us to jot down what we considered to be characteristics of a good spec for a software feature (from a writer's POV). My contribution:
That's not too much to ask for, is it?
If you're the writer and you're not involved in your team's spec reviews, ask to be included. Read the specs, ask questions, make suggestions. Remember, whatever they develop from it, you'll have to explain to the customer.
(As a side note, that brings to mind one quality that a good tech writer must have -- the willingness to ask "dumb" questions. If you don't ask the question because you're worried that it might make you look silly, you're doing yourself, the customer, and the team a disservice.)
Back to specs. The spec sets the stage for the story that your documentation will tell. From the specs, you should be able to start crafting the high-level design for the docs: what the user will be doing and what they need to know to do those things, what method and organization for the documentation will be most useful for that type of information.
If the specs you work with don't include user interface mock-ups, finagle your way into those UI meetings and reviews as well. Look at each screen with the question "how am I going to explain this?" Be the customer's advocate: "Why am I clicking Next three times?"
Some components of management packs include product knowledge, which is just information provided by the MP author (as compared to company knowledge which is information provided by the user in their own copy of the MP). We're working on internal guidelines to help MP authors provide effective knowledge, so I'd like to know what your thoughts are -- what would you expect (hope) to learn from the product knowledge for any or all of the following components?
Please leave a comment here or send email to firstname.lastname@example.org!
A recent comment by "BPM software" suggested that I write about best practices for writing technical documentation. I thought about it for awhile and decided I couldn't really do it justice in one post - hence, "part 1".
I'll begin by plagiarizing myself. What I said about management packs is just as true in this context:
Ideally, good technical documentation tells you everything you want to know and doesn’t tell you anything that you don’t want to know.
The key in that statement is you. Whether the content is good, whether it answers your questions, whether it avoids wasting your time with irrelevencies...all of those are defined by you, the reader.
Just about every book/class/seminar/workshop on communicating effectively starts at the same place: know your audience. Why? Because I have to know who you are so I can figure out what you'll want to know and what you don't want to know. It's really easy when it's 1:1, like when I write up instructions for a relative.
There are just too many readers in the professional world, though. So technical documentation tends to become "everything anyone might want to know" because we usually prefer to offer at least some value to many rather than great value to just a few.
So, the first best practice is to define your reader (customer, user) as best as you can. To document software, I consider the two main questions to be:
To answer the first question, you need to learn about the problem your reader has that he wants to solve, about the environment he'll be in, and about his expectations for a solution. All of this information helps you define what the reader wants to know and, in combination with the answer to the second question, helps you define what he doesn't want to know.
Your answers to the questions may also reveal that you have more than one type of reader. Take Operations Manager, for example. We have customers who want an efficient method to monitor many servers. We also have customers who want an easy way to create their own custom monitoring solutions. Some of those customers are support technicians who want documentation that will help them monitor and some of those customers are developer-types who want documentation that will help them create customized solutions. So right there we have two very different readers who need distinctly different documentation.
When your readers have different goals and different levels of knowledge and experience, don't try to write to all of them in one document (if you can avoid it).
I'll be honest, we're not fully there yet with Ops Mgr. Some of our documentation tends to skirt between those two readers. We recognize that we've muddied the waters a bit, which serves neither reader very well, and we're working on repairing that problem in future versions.
Sometimes I read spam email before I delete it, just to see if anyone is getting more inventive. The recent trend is to claim to be from the FBI and to assure me that they've cleared my transactions with the foreign government.
I got a new one today, though. All this person wants, to release "my" funds, is two 120GB USB hard drives.
"I am Engineer Richard Mongo A Central Processing unit, known as computer scientist with African Development Bank. I am 29 years old, presently working with African Development Bank. I came across your file which was marked X and your released disk painted RED, I took time to study it and found out that youve met VIRTUALLY all fees and certificate but the fund has not been release to you. The most annoying thing is that they cannot tell you the truths that on no account will they ever release the fund to you; instead they let you spend money unnecessarily. I do not intend to work here all the days of my life, I can liberate this fund to you if you can abide by the rules and regulations to make this transfer successful to which ever method suits you, also promised to pay compensation of 10% percent of the total fund if I make you recover all what you might have lost in the past and help to re-establish your precedent bliss. The only thing I require to release this fund is a special HARD DISK we call it HD 120 GIG USB. I will need two of it to enable me recopy your transfer information, which I will destroy the previous one, and punch the computer to reflect in your bank within 24 banking hours and clean up the tracer then destroy your file, after which I will apply for resignation for my trip to your country for my percentage, or better still an ATM-CARD method payment can be granted if you are interested don't hesitate to get back urgently. You ought to send a convenient Tel/fax number of yours for uncomplicated communications and also reconfirm your banking details so that there won't be any inaccuracy. Note with the intention of your fund payment which has been taken to offshore for payment in other country are now mandated to offset by the Development Bank Of Africa due to the originator of your fund payment which is located here in the Africa continent."
I'm afraid I'm going to spend some time trying to figure out what precedent bliss is, and whether I really want it.
The latest Active Directory Management Pack package includes management packs for monitoring Windows 2000 Server, Windows Server 2003, and Windows Server 2008. Each server version has a .Discovery management pack and a .Monitoring management pack. You may decide that, since you're only monitoring Windows Server 2003 (for example), you won't bother importing any of the other server version management packs, only to have a problem because Operations Manager tells you that you're missing some required management packs -- what's going on?
Working on management pack guides, my attention is generally on how you can use the management packs we create at Microsoft. Next week, however, I'm attending a daylong workshop on authoring management packs. I'm hoping to learn a lot (unless it all goes over my head!).
But if I didn't have the opportunity of this workshop, how would I go about learning to create management packs? Well, first I would download the System Center Authoring Console. Next, I would download and read the Management Pack Authoring Guide. Finally, I would take advantage of all the great resources at the AuthorMPs site.
I'll let you know next week how the workshop goes!
You might notice in the management pack guide library that some guides are quite extensive (like Active Directory) and some are a single webpage with "ReadMe" in the name (like FRS). You might also notice in the installation folder for some management packs that there are two documents: a guide and another that has MPAdd or ReadMe in the name.
What's going on with those? Last year and early this year, a number of MOM 2005 management packs were converted for Operations Manager 2007. When we released the converted management packs, we included the original documentation for the MOM 2005 management pack and added a supplementary document to provide any information that was unique to the converted management pack. Not rewriting the guides was primarily a resource decision, so we could make more management packs available more quickly.
What that means is if the supplementary document (which is specific to the Ops Mgr 2007 MP) says one thing and the guide (which was written for the original MP) says another, the supplementary document is correct. We just didn't explain that clearly enough in the supplementary documents.
I'm clearing out some of the blog posts I've clipped over the years and came across one that I saved when I was working on DPM. Jonathan Schwartz's article on how long it takes to move a petabyte of data caught my attention because it related to the DPM issue of when you might prefer tape storage to disk storage.
A petabyte is awfully huge, of course. As he explains, "A petabyte is a thousand terabytes, which is a million gigabytes, or a billion megabytes. Or 8 billion megabits." But thinking it over...my own little PC at home has 500 GB now. And 2000 workstations could be a decent size company. Not that all those workstations would fill up their 500 GB hard drives, but it made the data size not so inconceivable to me. Lots of servers, lots of data to maintain and archive - the numbers could get pretty big.
Then he does the math:
"So if you had a half megabit per second internet connection, which is relatively high in the US (relatively low compared to residential bandwidth available in, say, Korea), it'd take you 16 billion seconds, or 266 million minutes, or 507 years to transmit the data."
Thus supporting his contention that it is "faster to send a petabyte of data from San Francisco to Hong Kong by sailboat, than by the internet." Cool, huh?
This is a question about the root page for the two management pack guide libraries (operating system guides and server guides). All of the guides are listed in the left navigation pane, beneath the parent page:
In addition, when you click the parent page itself, the guides are listed and linked on that page:
The question is: does the list on the parent page ("Guides available in this section"), which mirrors the navigation pane, add any value for you? If we removed the links from the parent page and you had to use the navigation pane instead, would you care?
I'd really appreciate your opinions, either by leaving a comment here or emailing mpgfeed AT microsoft.com.
Catching up on my Microsoft-related blog feeds this morning, I counted at least a dozen blogs announcing the new Windows 7 blog -- some rah-rah posts, some just passing it on, some speculating as to how much information the blog will actually provide, plus some conversations on the pros and cons of transparency.
Coincidentally, last night I came across an example that illustrates when transparency is the best solution for a situation.
You see, the town of Hickman, Nebraska has made national news because they want to evict an old horse from city limits. I'm guessing that they've been inundated with queries, complaints, and accusations as a result. So, they turned their city's homepage into a timeline of events to explain the situation to all of us who probably couldn't find Hickman on a map and have no intention of moving there but feel it's our business whether the horse stays or goes. (You can probably tell that my sympathy has shifted toward the town's side...)
In my aspect as a customer, I'd be fascinated by similar disclosure about a product in development. But I can also imagine reading "Discussed flippeting the gibbet. Decided it wasn't feasible in this timeline." and being disappointed, because although I'd never had cause to flippet a gibbet before, now that it had been suggested and taken away, I wanted that feature back!
Thanks to a sharp-eyed customer, an error in the resolution procedure for alert "SDK SPN Registration" has been identified. The resolution is below, with the error and change in bold:
You can use SetSPN.exe to register the SPNs for the SDK service. Here are the commands that you need to execute using an account which has domain administrator rights:
Setspn.exe –A MSOMSDK/[RMS FQDN] domain\username (this is the SDK service account name)
Setspn.exe –A MSOMSDK/[RMS NETBIOS] domain\username
You can use SetSPN.exe to register the SPNs for the SDK service. Here are the commands that you need to execute using an account which has domain administrator rights:
Setspn.exe –A MSOMSdkSvc/[RMS FQDN] domain\username (this is the SDK service account name)
Setspn.exe –A MSOMSdkSvc/[RMS NETBIOS] domain\username
Update: edited the commands to replace the less-than and more-than signs with brackets, because they caused the commands to display incorrectly in html - sorry!
The next revision of the Operations Guide for Ops Manager will include an expanded section on management packs. We've added some procedures (both GUI and script) and some conceptual information. Here's a preview from the management pack lifecycle topic:
Best Practices for Change Control
The following are some best practices to follow when managing Operations Manager management packs:
I've really enjoyed the blog WW1: Experiences of an English Soldier which posts Harry Lamin's letters during WWI, each exactly 90 years from when they were written. The blog format, parcelling out the letters in real time + 90, makes the reading experience seem more genuine than the same letters packaged all at once in a book would (IMHO).
So I'm really looking foward to The Orwell Prize blog which will be taking the same approach by publishing George Orwell's diaries, each entry 70 years from the date it was written. The diary entries will begin appearing Aug 9 - mark your calendar!
I know many of you have been waiting anxiously eagerly for management packs for Windows Server 2008. The support statement has been released and now we can start publishing them to the Catalog. Be sure to read Clive's post carefully, he calls out some important information that you'll want to be aware of.
I'm not a hardcore gadget junkie, although I've bought plenty that I never really use...maybe a semi-junkie. Most of my gadgets are from Woot because at 10 p.m. pacific time when I refresh their site, it's really easy to convince myself that I have to have that (whatever it is). My most recent impulse was the Pinnacle Video Transfer. I have several old home movies on VHS that I've been worrying about losing, and the last gadget for VHS-to-PC transfer that I got failed miserably.
So I decided to try this. And I'm blogging about it because so many of the comments on the Woot blog wondered if it worked with Zune.
The answer is, not directly. However, I transferred the VHS tapes to a USB drive, then attached the drive to my computer and copied the resulting videos over to a folder monitored by Zune. Zune found them instantly and synced them to my device, where they played with no problem. Very easy and satisfying! And now I can sleep better, knowing my daughter's high school graduation is safely reproduced in digital form in multiple locations. (Also, back in the 80s, there was a chain of "Be a Star!" stores, where pre-adolescents could get makeovers, costumes, and then lip-synch in their own personal music video. I also salvaged that tape, to my daughter's chagrin!)
Most everyone has heard some of the stories about the frustrations of providing tech support. Here's a fun one that Help writers will appreciate:
My friend Duane was on duty in the main lab on a quiet afternoon. He noticed a patron sitting in front of one of the workstations with his arms across his chest as he stared at the screen. When my friend asked if the guy needed help, he replied, "It's about time! I pushed the F1 button over 20 minutes ago!"
So it's understandable that an admin might get fed up at times. But holding the password to the city's network hostage is...extreme, no? (I can see it as grounds for being fired, but I'm really curious which law they charged him for violating.) Although there are probably many admins who would sympathize with the lawyer's explanation:
"Mr. Childs had good reason to be protective of the password," Crane said. "His co-workers and supervisors had in the past maliciously damaged the system themselves, hindered his ability to maintain it ... and shown complete indifference to maintaining it themselves."He was the only person in that department capable of running that system," Crane said. "There have been no established policies in place to even dictate who would be the appropriate person to hand over the password to."
Part of me had been dreading this day. Once I had thought my 30 GB hard drive was spacious; then I acknowledged a bit of crowding by adding an external USB drive; but finally I had to admit that C: was just too small - I kept running out of sufficient free space to run Neverwinter Nights, which uses a lot of temp space on C: even though the program runs off the external drive. So I ordered a new drive (500 GB, it should be big enough for awhile) and waited for my first day of vacation to deal with it.
In my experience, when getting inside the box, it's more likely that something on this scale will go wrong and need troubleshooting than that it will just work. Knowing that, I first reviewed the basic procedure (found a wonderful primer on cloning XP at PCstats). I made a backup. I upgraded Acronis True Image, which I planned to use for the cloning.
Step one, install the new drive as a secondary drive. Minor fumble here, because the primer recommended booting to the BIOS to make sure it was recognized (it wasn't) but on the next attempt I missed the window for the boot menu and when XP started, it found the disk and offered to initialize it. Cool.
Step two, clone C: to the secondary drive. I used the manual option so I could make the future C: use the full space. (Yes, I know there are performance and security arguments for multiple partitions, but over the years I've learned that I'm most satisfied with one large space.) Cloning the 30 GB to the 500 GB took almost exactly three hours. I read a book.
Step three, swap the cables from the 30 GB to the 500 GB, change the jumper setting on the 500 GB, remove the 30 GB, boot.
Flawless. And faster. It doesn't get much better.
Last month, I announced that we'd started adding Ops Manager 2007 management pack guides to our online TechCenter. I'm relieved happy to let you know that the guides for Windows operating systems and technologies and the guides for server products are all online now.
If there's a 2007 management pack (from Microsoft) that is missing, please let me know at email@example.com so I can fix it!
I know the direction of the ceiling fan is supposed to make a difference -- one way in cool weather to circulate the heat, and the other way in hot weather to provide cooling. But each spring and fall, I have to look it up because I am never certain if I remembered to set the direction properly the previous season.
Now that we're going into summer (in the northern hemisphere), you want the fan rotating clockwise.
The Management Pack Guide library is now live on TechNet. About half (23) of the Operations Manager 2007 guides are available in the library now, with the rest to be added over the next few weeks. The guides are organized into Operating Systems & Technologies and Server Products for easier browsing.
I almost forgot to add...we've included the Community Content widget on all of the online guides, which means you can add tags and submit your own content to enhance the information in the guides.
I posted last month about the "missing" management pack guides for the management packs that were included with SP1, and finally have progress to report. As I stated, our goals were to:
We've packaged the individual management packs with their updated guides, and the first batch has appeared on the Operations Manager 2007 Catalog:
More should be added to the catalog shortly!
Previously, I learned what management packs version numbers mean, but that will be changing in the near future. Coming soon, the part of the version number that was previously tied to the version number of Operations Manager (6.0.6278.22) will be the version number of the management pack, and the part that was the management pack version (6.0.6278.22) will be incremented for updates to the management pack.
The details page for the download and the management pack guide will establish the required version of Operations Manager.