Monthly Archives: May 2006

talk.bmc

Defining OPML and relating to DITA maps

I found a nice definition for OPML from whatis.com as their word of the day, and I’m starting to wonder about similarities between OPML and DITA maps

From an information design perspective, OPML is a great format for outlining information, showing information’s hierarchical structure and relationship to other entries. I had only really thought about OPML applications as advanced organizers for lists of RSS feeds, but I suppose there might be other applications as well. This definition on whatis.com alludes to multiple organizational uses for OMPL, saying “…OPML has been used to organize many kinds of data as it may be customized for each application.” But what are these other uses for OPML? Can anyone point me to examples?

I sometimes find it difficult to articulate my enthusiasm for OPML, and this definition offers a great overview. I always have seen OPML as a great way to store lists of RSS feeds in logically-named folders. Here’s another excerpt from the definition:

OPML allows a user to classify where content should be placed within a hierarchy as it is being created. This feature makes the format extremely useful for the creation of “living documents,” where relationships and content are continuously updated.

I think that OPML and DITA maps may be closely related cousins in the list family. From the DITA specificiation, DITA maps organize topics for output to a specific deliverable, including generating navigation files and links to related topics. DITA maps offer the ability for quick re-organization of topics to create multiple deliverables. I envision DITA maps as offering an alternative to single-sourcing by letting you pick and choose from a large array of topics, whittling the DITA map down to just the print book combination or just the online help combination that you want. With the power of DITA maps, you can create two subsets of documentation from the same superset of topics. I think that the “living document” description for OPML is also fitting for DITA maps. Just ask Jen Linton, who co-authored the Introduction to DITA: A User Guide to the Darwin Information Typing Architecture book using DITA. She was able to completely re-organize the book within weeks of publishing by simply changing the DITA map. Nice! Now we just need a drag-and-drop interface for editing DITA maps.

If you’d like to work with an OPML editor, there’s one you can download on the opml.org site. And remember that there’s a TalkBMC OPML file available for downloading that contains an organized list of all the blogger feeds, comment feeds, and podcast feeds for talk.bmc.com. Very handy!

talk.bmc

MS-DOS tips for time and date stamps

How to make zip files and folders with a formatted date and time stamp as the folder name in a DOS batch file automatically

We have a help rendition system internally, where all we writers do is create the source files needed to make CHM files (HHK, HHC, HHP, HTML), zip up the HTML source in a certain way with a certain file name, and submit it using a webform. Out of that rendition engine we can get CHM, JavaHelp,WinHelp, NetHelp, or our internally-created cross-platform help called Browser Help. Browser Help is the system that works with BMC Performance Manager and I’ve posted before about how to create those help systems automatically.

Since I needed to render several help systems at once, meaning I had to make multiple zip files containing the right content with the right zip file name, and I dislike tedious repetitive tasks, but somehow I like the tedium of testing and using scripts, I used DOS batch files to do the file creation and name formatting for me.

Today’s tip is how to make folders with a date and time stamp as the folder name. Our rendition engine likes its zip files with a certain naming convention. As an added bonus, this routine works before and after ten in the morning. Silly DOS, it doesn’t put a leading zero in unless you tell it to. Here’s how to tell DOS to put in the leading zero if the current time is prior to 10:00am.

REM Create sub directory called \yymmdd_hhmmss

REM where yymmdd_hhmmss is a date_time stamp like 030902_134200


set hh=%time:~0,2%

REM Since there is no leading zero for times before 10 am, have to put in

REM a zero when this is run before 10 am.

if "%time:~0,1%"==" " set hh=0%hh:~1,1%

set yymmdd_hhmmss=%date:~12,2%%date:~4,2%%date:~7,2%_%hh%%time:~3,2%%time:~6,2%

md h:\%yymmdd_hhmmss%

A Command-line reference A-Z that contains all the reference information for DOS command-line parameters is available on the Microsoft site.

Edited to add: Note that this script does not work for times between midnight and 1:00 am.

talk.bmc

SplunkBase – tag your IT

A wiki as a technical information repository, for sysadmins by sysadmins

Cote passed along SplunkBase to me a while back as an example of a wiki that houses technical information, and it looks like Slashdot got a hold of SplunkBase early in April with SplunkBase Brings IT Troubleshooting Wiki to the Masses.

I had challenged everyone on my internal BMC blog to send me good examples of wikis for technical documentation. So far SplunkBase is the most interesting and discussed example I’ve found so far.

SplunkBase is not Splunk

The name (which took some flack from slashdotters) does derive from the term spelunking, or exploring caves for fun.

To be clear, the freely available SplunkBase is not the same as the fee-based product Splunk, which indexes your log files and has a nice review and better explanation from a user here. His company has a Gig of log files generated a day, and he posted a sample log file to SplunkBase for an Input/output error from courier impad when there are FAM problems. His description also offers a fix (either install or restart portmap and fam). To me, this is a great example of users helping users through collaborative content generation.

Industry analyst Dana Gardner has a good discussion of it in a recent podcast with Chief Executive Splunker Michael Baum and Chief Community Splunker Pat McGovern (of SourceForge fame).

Livin’ in your logs

Those two talk about how sys admins live in the log files, constantly troubleshooting and walking through this highly unstructured data trapped in a log file. Lots of people have compared Splunk Base to grep and awk with a more Google-search-like interface. Search and navigation are the biggest two productivity boosts when it comes to searching through unstructured data. Couple those boosts with the power of a large user community contributing content and I think they’ve got something there. Imagine Wikipedia but for discoveries in your log files rather than a encyclopedia.

Are you kidding? Share my log content with others who might be hackers?

An immediate concern about sharing content such as the contents of your log files is keeping data scrambled and anonymous. In other words, how do you ensure that you aren’t giving away your IT infrastructure when you upload your log files as examples or broadcast to the world via a wiki page what you learned while troubleshooting your company’s IT environment. In the podcast, about halfway through they talk about how they’ve built in an event anonymizer before it’s shared with others. Most IT data is timestamps, usernames, machine names, IP addresses, that occur repeatedly, but this anonymization process scrambles that type of common data repeats in a way that you still recognize the repeated event or IP address, but you can’t reverse engineer that company’s infrastructure (except for what version of SendMail or Microsoft Exchange is used.)

In the podcast, they do congratulate Cisco on doing a nice job documenting log files, but most vendors aren’t really focusing on that information. A wiki just might be the right way to document log files. What do you look for in good log documentation?

In closing, I’ll challenge all of you as well — where are you seeing good examples of wikis or other collaborative authoring environments for technical information?

talk.bmc

Learning more about DITA

Learning about how to get started with DITA and a trivia item for fun

Jen Linton, the co-author of Introduction to DITA:Getting Started with the Darwin Information Typing Architecture is in Austin to teach the DITA Getting Started workshop hosted by BMC Software. I’m attending along with several of my co-workers, and we’re all learning a lot.

Last night I went to dinner with Don Day, chair of the OASIS DITA Technical Committee, Jen, and Wendy Shepperd, a manager here at BMC. Jen asked Don, “What’s the story with the bird in the DITA logo?” I had blogged earlier that it’s a finch with a specialized beak, but it turns out there’s more to the story. Don explained that it’s a woodpecker finch, one of the finches Darwin documented from the Galapagos Islands, and it’s a tool-using animal. Woodpecker finches pluck the spines from cacti or use wooden splinters to extract grubs and other bugs from holes that their beaks don’t fit for a tasty meal. That’s a fun piece of trivia. Here’s the logo to which I’m referring.

After dinner we went to the Central Texas DITA User Group meeting, where Jen told and showed us how she assembled the Introduction to DITA book using DITA topics. The most interesting part for me was to learn about the Mekon FrameMaker plug-in that lets you import DITA content into FrameMaker for book assembly and above all, index generation. Nifty! It’s part of the DITA Open Toolkit if you browse the CVS repository.

In our training class, we wondered out loud where all the local User Groups are forming currently, and I found this list at http://dita.xml.org/user-groups:

Canada

United States

talk.bmc

Celebrating moms and parenthood in the workplace

Parenting, does it make you a better employee?

We celebrated Mother’s Day in the U.S. yesterday, and I came across an article that I enjoyed. I thought I’d share in celebratation of moms and parents everywhere.

This USA Today article, Do moms make better managers? is a great read because it is brutally honest about both sides of the argument. (In case you’re wondering, the answer is, “It depends.”) My favorite observation from the article is the gender-bias-free one, which is, “You are the sum of your life experiences.” For me, working full-time while going to graduate school was a life experience that taught me how to prioritize and get more done on less sleep. The same can be said for me as a mom of a two-year old, get the important tasks done early (and know what’s important, as in, don’t sweat the small stuff.) To me, the funniest quote from the article is this one:

Denise Morrison, president of Campbell Soup’s U.S. soup, sauces and beverages division, worked while her daughters, 27 and 25, were growing up – and while Nestlé’s director of marketing, she was still able to squeeze in a stint as Brownie leader. “They were a results-driven Brownie troop,” she says.

Hee hee. Thanks, Diane, for sharing this gem!

Looks like Peter Armstrong is feeling like a proud parent when it comes to BSM. Yes! We’re all feeling that way with these new workflows and product integrations and Atrium CMDB maturation. Plus, the third-party integrations are getting really exciting.

Even salary.com is in the spirit, with a new calculator called the Mom Salary Wizard, as described in this article, Being a mom could be a 6-figure job.

Parent or not, paid or not, life experience, however and whenever we get it, is what I’ll celebrate today.

talk.bmc

Connect the dots, or pixels, for service impact

Sometimes a combination of zoom in and zoom out lets you get the big picture out of lots of parts

I’ve read or seen several items lately that are related to using pixel- or grid-based design for arts and crafts. It seems like pixel-based art is everywhere. Take a look at some drawings done in Excel, and if you like, buy the new book, 58 days worth of Excel drawings.

My personal favorite is this Mario quilt, posted on craftster.org. What a great project and accomplishment.

So what does pixel-based art have to do with service impact? I’ve been reading about and learning about BMC Service Impact Manager and trying to see how the dots connect to the CMBD and our BMC Topology Discovery product, which doesn’t require agents for discovery. Super Mario isn’t jumping out of any of the topology diagrams I’m seeing, but I completely understand why sometimes you need the larger diagram as well as an overview diagram so that you can troubleshoot a problem with a complex SAP installation.

The BMC Topology Discovery product has an Expert Extension for SAP. With it, you can automatically discover the applications deployed in each SAP ID, including the logical and physical infrastructure. Don’t build these models by hand, let an automatic discovery tool find the connections for you. Plus, changes are detected and updates made immediately.

I doubt that any art projects will come of topology maps, but if you see any interesting graphical patterns, please do share!

talk.bmc

Municipal wireless access

I love living in Austin even more now, they’ve added city blocks worth of wifi access

Right before the World Congress on Information Technology commenced last week, Austin mayor Will Wynn pushed a big white button in front of a coffee shop downtown, and 28 wifi access points gave access to an area extending from Town Lake on the south to 7th Street on the north, and from Lamar Boulevard on the west to I-35 on the east. That’s nearly 18 blocks by 6 blocks, we’re talking about 108 square city blocks of wireless access. Yet another great reason to call Austin home. Here’s the news story, Downtown wifi network goes live. In June, the network expands to East Austin, and in July, Zilker Park will join in.

I wonder what sort of service level they’ve agreed to for this network. Apparently Google’s Mountain View Wifi efforts hit a snag, requiring installation of more access points. I know from hearing about wireless installs at the dinner table that thick concrete walls, strange valley and rock formations, and even bushy trees can make for a touchy network. Sure hope the Zilker Park additions are well-designed and architected as there are plenty of interesting rocks, trees, and waterways there. Are customers more lenient about wireless access than “regular” network access?

talk.bmc

Best practices in technical communication for customer feedback

Many technical writers pride themselves in being customer advocates. What are some best practices for connecting with customers?

For another part of an informal series about best practices in technical publications, I want to discuss customer interaction with writers and getting customer feedback about your technical documentation. How can technical writers ensure they are making the right customer connections to best help a company succeed? A few of the best practices listed in the “Tech writers as sales reps?” that the panel referred to for our Austin STC Meeting in October 2005 that are related to customer interaction are:

#7: Encourage technical writers to meet customers.
#8: Use customer advisory boards to get feedback on documentation.

Q: Customer interaction – let’s discuss the constraints on really making this happen. How have you made it happen?

A: These managers had done a lot of things to get customer feedback, from customer surveys to online feedback forms embedded in the online help. Bill Hunter guest-blogged about online feedback forms previously .

All the manager panelists liked the concept of a customer advisory board, citing that as a great best practice. Also scheduling your writers to have lunch with customers when they’re on site for training is a great idea.

One manager said from her experience that she finally understood why it wasn’t always a good idea to have writers talking directly to customers, due to the issues that a writer may not be able to resolve to the customer’s satisfaction because the politics are out of their realm of expertise or influence. Also, our curious nature might lead us to ask questions about our own tools that might not have the best answer, leading to awkward, shoe-shuffling moments. So, in this manager’s perspective, she felt that writers should not meet directly with customers unless they are trained on how to work with customers and guide discussions so that you answer questions correctly or help with things that are fixable (and realize not all perceptions can be fixed). If you’ve worked in IT for any amount of time, you know about these perceptions and what can and can’t be fixed.

Getting customer feedback can be a best practice to put into place, but you may not always get an immediate positive result. You have to ensure that your doc team can succeed by setting expectations for the requests to avoid unrealistic requests based on time or resources available. Still, any time spent with customers helps us take a walk in their shoes and should offer both participants valuable insight into the other’s position.

This post continues the series about best practices in technical communication where I blogged about:

Questioning technical publications best practices

Best practices in tech comm for fit in the organization

How to implement a document or records management system that meets ISO standards