Monthly Archives: July 2006

talk.bmc

Happy Sysadmin day!

Show your support and appreciation for all the sysadmins who keep your email (and other business services) in tiptop shape

My sysadmin husband asked me this morning what I’m getting him for System Administrator Appreciation Day and I drew a blank. But now I know, the last Friday in July (July 28th for 2006) is System Administrator Appreciation Day. So check out these gift ideas and give your favorite System Administrator an extra smile or thank you today. Keep an eye out for cartoons celebrating the day as well.

Keep up the great work, sysadmins everywhere!

talk.bmc

Eating our own dog food, or sipping our own champagne

How we strive to achieve BSM at BMC

Eating your own dog food. The phrase comes from the early television advertising genre when people would ask, but will the dog eat the food? Today it’s categorized as a computer jargon phrase, well-documented in a Wikipedia entry, describing how software companies and other industries try out their own products, putting themselves in their customers’ shoes. I assure you that at BMC, our IT group often pops open cans of our dog food, or sips our own champagne, as Thomas Siebel prefers to call it.

My favorite essay on the topic has to be Joel Spolsky’s “What is the work of dogs in this country?” essay from 2001. Read both the Wikipedia link and the essay for all the nuances and pros and cons of eating one’s own dog food. I especially like Joel’s example of how the Juno executive wanted six pop-up ads until he experienced it himself and then backed off to two pop-up ads.

Similarly, I have heard people ask over and over again, this BSM stuff sounds great, but are you really doing it internally, BMC? That type of question is the heart of eating one’s own dog food. “Sounds great, but have you put it into practice? Show me.”

In the spirit of documenting how we eat our own dog food, I recently completed a white paper, “Implementing Resource Management Using Business Service Management Principles.” It’s about how our research and development lab schedules server resources for testing. This scheduling is no small task, especially in an Agile development environment with iterations that might go for 2 weeks or 4 weeks. The products we test also may need to be tested on 14 different platforms. I think the team used a half dozen BMC products and intend to use even more in the future, such as the advanced discovery and provisioning tools we have available. Products consumed so far, with more on the way:

So take a look at the paper – no registration is required – and let us know what you think. This IT group, including talk.bmc’s own Steve Carl, is constantly looking forward to make their processes even more business service centered.

talk.bmc wiki

Found a Microsoft tech writing blog

Tech pubs at Microsoft, one blogger’s view

In addition to being an interesting view into tech pubs at Microsoft, the blogger talks to MSDN Wiki product managers. So I wanted to be sure to point to Harry Miller’s Technical Writing Blog. A few weeks ago he posted a podcast where he interviewed Molly Bostic, who is a PM on the MSDN Wiki which was recently released. Worth listening to, only about 15 minutes long. I have to admit I have a short audio attention span. I can read for hours but listening? Not so much.

She talks about the feedback they’ve received so far and even addresses one of my questions about protecting their wiki content from “graffiti” as I call it in this post, although she refers to unwanted wiki content as spam. As a team they are also addressing issues related to authority, such as, how can individual users get more “cred” on the site, and how can readers of the wiki find out which posts are the most valued. I also was interested to learn that due to the Creative Commons license they’ve selected, they cannot roll back the content into Microsoft’s online help or knowledge base.

talk.bmc

Examples of software and IT services related to business

The reaction to the problem more important than the root cause

I was intrigued by the tagline on this new blog, g2zero: Better Code == Business, which I take to mean that better code is equivalent to better business. I wondered if they would be like-minded about the principles of our Business Service Management concepts, so I took a look. And, I was rewarded for my perusal with this gem of a post: Entries from the Software Failure Hall of Shame. It has several examples of software problems and their direct affects on the business’s bottom line.

Yes, software and IT services will fail, but your ability to react and keep the priorities of the business and the customer first will set the standard for your success. This Toyota Prius hybrid car example is an excellent one, showing that you can manage your incidents gracefully and proactively and avoid negative publicity. I have posted before about hybrid car technology so this was right up my alley.

The Toyota Prius engine management flaw. In October of 2005, the Toyota Motor Company voluntarily recalled 75,000 of its hybrid vehicles because a software glitch that may have shut down the engine. Given the high price of gasoline at the time and the rising interest from consumers in hybrid vehicles, the recall could have been a major blow to the manufacturer. However, due to Toyotas quick response, most consumers never experienced the flaw, and while the company may have suffered slightly from the negative publicity, it managed to avoid having its defect become permanently associated with the vehicle line or with hybrid safety.

Great set of examples. I plan to keep an eye on this blog.

talk.bmc

Alterpoint blog gives kudos to our Routes to Value approach to BSM and ITIL

Breaking down best practices by making the parts easily accessible

Alterpoint is located in Austin (where I’m located) and makes network management software that is integrated with our BMC Remedy Action Request System and BMC now resells their product, DeviceAuthority. With just a couple of “follow this idea” clicks, as often happens when I read blogs, I found this blog entry, ” Break it Down: Making Strides with ITIL and Best Practices.” In it they give props to BMC for creating the BSM Routes to Value that make the sometimes daunting task of implementing best practices for IT manageable — by breaking it down into parts that make sense. My favorite lines from this post are these, because it mirrors my own observations lately.

One of the basic points is that these transformational projects have too much at stake to be threatened by internal pride or lack of good internal assessment. To realign around ITIL or other best practices, you often need to adjust, enhance or expel some process and cultural factors that are baked into your operation before you even start talking about technology.

I’ve got a white paper in progress where I offer observations of methods for implementing ITIL best practices, starting with the infrastructure tools you already have in place, and in it I discuss getting started with small projects that can later add up to more. You hear corporate culture stories when you start to talk about ITIL projects, and Gary Holmes has some great observations in his comment on Throw out ITIL, but keep the CMDB?. I look forward to hearing more corporate culture and organizational communication stories as I continue to learn about this IT Infrastructure Library myself.

talk.bmc

A web-form based DITA editor

Could this be the perfect storm for a DITA wiki?

Written with just HTML, Javascript, DOM, and CSS, as far as I can tell, DITA Storm is a product that enables web-form-based DITA topic authoring and display. Go check it out, their web site has a lot more content now and you can even request a copy with which to play.

As my help infrastructure buddy said, “This is so cool I think I’m going to freak out like this kid. Nintendo Sixty-FOOOOOOOOOOUR” Yep, it’s Friday, so yep, it’s a video link. Just go watch it, and get a good laugh.

I’m imagining that you could do several things with a web-based DITA editor (and topic styler). One thing would be a DITA-based wiki, where you author directly using DITA topics rather than some cryptic ASCII codes for headings and bulleted lists and so forth. End users don’t have to know DITA to enter content, either. Although I do think you’d want to also be able to copy and paste content from existing DITA topics, and I’m not sure how you’d do that (maybe there’s a “view XML code” feature in the works?). Although you can just link right to the XML topic from within the HTML page, which would be nifty for DITA topics you already had waiting in the wings.

According to the web site, “The prototype version 0.3 of DITA Storm supports following DITA elements: topic, title, shortdesc, body, section, title, note, lq, q, fn, related-links, link, linktext, desc, p, b, i, u, tt, sup, sub, task, taskbody, context, result, steps, step, cmd, stepresult.” So it is a subset of DITA so far (others are subsetting DITA but it’s not really DITA once you subset it and you can’t import DITA-compliant content later into your subsetted set. Whew.).

Another idea for using DITA Storm for end-user doc might be to build your context-sensitive help system right in with your web interface product. I suppose this idea would work only if you can lock down the content at a certain point. But the stylizing with CSS is very promising and really lets you do anything you want with the content. The stylized examples are really nice looking, such as a stylized task topic and a stylized basic topic.

And, my pet idea would also be to use DITA Storm to write blog entries. Entering blog posts in a structured language like XML would work right in with the microformatting concept. Build the next blogger.com site using DITA Storm.

This type of product in my estimation has the potential to be the next Writely, stealing from the desktop publishing user base with the beauty and simplicity of a web editor that just gets the job done. Yes, it’s another way of writing, but a nifty little tool that could help your content do some interesting cartwheels.

talk.bmc

MSDN has a new wiki for Visual Studio

Microsoft has a wiki for end-user documentation for Visual Studio 2005

Cote tipped me off to a really fresh new wiki on MSDN for Visual Studio. It appears that they’ve compiled a lot of developer tips and tricks in scattered locations on the MSDN site, and this wiki is the initial move towards pulling it all together, with an eventual move to put the info from the wiki into the TechNet documentation collection.

They just opened for business so to speak last Thursday (June 8, 2006), and they’ve already got over 300 community content blocks. Their guidelines say to use the wiki to add code examples and other short bits of useful information, not to use it for long discussions or bug requests, which makes sense. So far the few code examples I’ve read through look useful, so I think it’ll become a great repository while you’re perusing the reference information. All of the content I looked at so far appears to be imbedded with the reference information.

You definitely need to use IE to browse through the content — they intend to support Firefox eventually but for now the display is pretty horrid in Firefox (extra scrolling due to extra separate textboxes.) It’s also English only to begin with, with some Brazilian Portuguese machine transation.

It’s interesting that they’ve added another source for information. One commenter on one of the team member’s blogs noted that there are no less than five locations within the Microsoft domain where you can find similar content.

I am definitely going to follow their wiki development with interest. Will they have trouble with sabotage or graffiti of sorts on the wiki, causing more maintenance? Will they test the code snippets eventually to ensure quality posts? Do they have someone constantly doing care and feeding and protection of the wiki, or is that just not necessary as the community patrols and corrects itself? Is most of the community internal to Microsoft so sabotage is unthinkable? What would they do with conflicting advice on the same topic? Geez, can I make wiki documentation sound more like a soap opera? Just kidding. Stay tuned and let me know what you think of their efforts and where BMC can learn some lessons.

talk.bmc

Adobe’s stepping up their tech writer toolkit?

Is Adobe wooing the tech writer market?

I’ll speculate freely about whether Adobe’s working on a tech writer workflow or toolkit, bouncing off of The Content Wrangler‘s prediction of a Technical Writing Suite from Adobe. (Thanks for the trackback enablement, Scott Abel!) And what a cool concept, a suite of tools that work together to help us tech writers, similar to Adobe’s Creative Suite. If the creatives can get such a bundle, why not the technical writers as well?

Here’s an interesting article and interview about Adobe’s newly sparked interest in RoboHelp. My favorite quote from this article has to be:

“But if Adobe truly intends to market an authoring tool called RoboHelp in 2007, it faces at least two challenges-in the user base and the code base. Macromedia’s stewardship did little to improve the RoboHelp technology-its aging kadov-laced HTML editor, the tack-on functions (some 12 years old) and a WebHelp output that’s like the bumblebee: it’s a miracle it flies. And as for the users-we know that story from several directions. ” from David Locke, WordSmith LLC.

Last week I attended the Benefits of Structured Authoring and Migrating in Preparation for XML webinar from Adobe (and played the Yeti batting a penguin Flash game while waiting for the presentation to start, a.k.a Pingu Throw). In it the presenter mentioned a DITA plug-in for FrameMaker (as well as other plug-ins, even though he said you can do all the XML authoring you want to with just FrameMaker. He probably should have qualified that as “FrameMaker plus plug-ins.”) Today’s seminar starts in about a half hour and it’s titled “FrameMaker and DITA” ( register here).

My take? Give us the tools and we’ll build some cool information systems. What do you think about bundled software systems geared towards a specific user base?

talk.bmc

Where to put your files and other setup for DITA

Working with the environment setup for DITA

I found this DITA Tip-Where to Put Your Files the other day and it’s a nice explanation of not only how to set up the file storage for DITA topics but also an explanation of why it’s convenient and what are the advantages to this set up. I think that the hows for DITA are readily available but the whys are a little bit behind. Everyone working on DITA knows about this general lack, though, and I think the gap is being closed. I actually think bloggers can close this gap somewhat. Take a look at the DITA category for martin’s blog for an example of where he discusses real-world tips for DITA.

Environment setup

I also followed the environment variable setup found in the Open Toolkit documentation (if you install the toolkit, the Windows instructions are in DITA-OT1.2.2/doc/installguide/settingenvironmentvariables.html) and found it really valuable. It doesn’t always say why you might use Xalan, or ANT_OPS, for example, so I’m not sure whether to bother setting those up if I don’t know the intended use. I guess I can’t expect too much from what is essentially a reference topic, and not a conceptual one. But, here is what I have gathered from reading the surrounding documentation:

  • Setting CLASSPATH for c:\ditaot\lib\dost.jar is optional but useful if you want to get logging information or debugging information. I believe that file was added in the DITA Open Toolkit 1.2 release timeframe. I went ahead and set it.
  • If you’ll use Saxon for XSLT processing, set up an ANT_OPTS variable containing -Djavax.xml.transform.TransformerFactory=com.icl.saxon.TransformerFactoryImpl.
  • Some settings conflict with others, so if you use Saxon for XSLT processing, remove all references to Xalan jars (another XSLT processor)from your classpath.

Which platforms work – plus the interdependencies

The DITA Open Toolkit 1.2.2 is tested on Java 1.4.2, Ant 1.6.5, FOP 0.20.5, and Saxon 6.5.3 releases. It ought to work with Java 1.5 but testing has shown that Java 1.5 works with Saxon but not Xalan. The whole toolkit won’t work yet with Saxon 8.x which supports XSLT 2.0. It also works with Xalan-J 2.6 but if you have Saxon jar files in your CLASSPATH, remove the Saxon jars before adding the relevant Xalan jars. In addition, to use Xalan, you’d have to ensure you’re using Java 1.4. (Yahoo dita-users group message reference) Whew! So many dependencies.

Set this, set that

One thing I’ve noticed on the dita-user group is that people will respond with, oh you need to set your this or that, but don’t always say where to set it. I found that often times people are referring to settings in the build.xml file that are properties that are defined in the doc/DITA-antscript.html file that comes with the Open Toolkit. For example, if all your topid files are .dita instead of .xml, this is the place you’d need to change to .dita in your build.xml file:
<property name=”dita.extname” value=”.xml“/>

Another observation is that oddly enough, in this case online install documentation has a huge advantage over printed because I can copy and paste URLs for downloading and environment variables to ensure accuracy. I had a tough time accurately typing \lib\avalon-framework-cvs-20020806.jar when glancing down at an open book. Plus, when I look at a printed book, I have to wonder if it’s really up-to-date, especially when versions and URLs are involved.

Troubleshooting

One great thing about this latest release of the Open Toolkit is a troubleshooting topic has been added to the help. So far there are only three common problems, and I’m having trouble with the third — Failed to load message file. However, so far, the suggested fix hasn’t worked. Still digging. I’ll keep you posted on my progress, though, in hopes of bridging that gap.

talk.bmc wiki

eBay offers an informative wiki

eBay starts the biggest commercial wiki yet

I love finding good examples of wikis, so my ears perked up when I saw the new eBay Wiki pop on my radar screen via the Read/Write Web blog. It’s part of their Community content authoring efforts and it’ll be exciting to watch it grow and mature.

The eBay Wiki is a collection of fact-based articles written and maintained by eBay Community members. You can use eBay’s Wiki to read up on topics important to you or contribute by adding topics or making existing articles better.

The information designers have done a good job of creating a navigation system with categories that are task-oriented, such as Buying, Finding, and Selling. Plus you can go into specific areas of auction interest such as antiques or baby items and so forth. To me, it’s a great example of a well-tended, easily-navigable wiki.

I’m not “into” eBay, having never bought or sold there, but I am definitely interested in their user-generated content, especially on such a large scale. Forbes.com had a catchier title for their article, and offers a more business-oriented analysis in “EBay Gets Wiki With It.” Especially interesting to me is how eBay hopes to save money with their wiki by cutting down on customer support calls. That inverse correlation is an often-used metric for proving that documentation is helping users, so I hope that they are able to track and link support cost reduction specifically to the wiki content.