- By Michele Marques, Lead Information Developer, ITSM

I entered the competition because:

• This was a new manual - everything good (or bad) about this manual was my responsibility. Many times, I work on manuals that have other contributors - or that originated with previous authors.
• I wanted to find out how my documentation held up to international standards.
• I wanted to get feedback from technical writers outside my organization.

I ended up winning a merit award. It felt great to get award and feel validated for my work. But the feedback was especially helpful. People from outside my organization had a different take on what works and what could be improved. Today the guide is better than ever.

I'm fortunate to work with a team of writers and editors, but for a lone writer, the competition might be your best opportunity to get feedback from experienced technical communicators.

- By Michele Marques, Lead Information Developer, ITSM

I'm writing this post from Lavacon in New Orleans.It's a really great conference, but this year's conference attendance is significantly lower than 2 years ago. It's no secret that conferences are having lots of problems getting enough participants this year. Since last year's economic meltdown, travel to conferences has been cut from many corporate budgets.

Some conferences offer virtual options. For example, the STC recorded all the sessions from their 2009 conference, and you can buy virtual attendance. You won't get to ask questions.... but you can attend all the sessions, and it doesn't matter if they were concurrent.

BMC is hosting a virtual conference.This conference is a live event, which means that you can ask questions and mingle with other participants. But, because it's virtual, you don't have to travel.

- By Michele Marques, Lead Information Developer, ITSM

Some of you technical communicators have been working for years in XML and DITA. However, until recently, I wrote all of my product documentation in Adobe FrameMaker. Sure, you can write XML documents in FrameMaker. But I had been using "unstructured" mode, which doesn't enforce structure.

I just wrote a doc for an upcoming release using an XML editor and the DITA DTD. I was nervous starting out - after all, I've been using the same tools for years, and XML involves a new paradigm. But I also knew that this was a great time for me to move ahead in the new direction. I was about to reorganize the manual that I was working on.

Some things are easier in an XML authoring environment

Have you ever tried to reorganize a manual? Cutting and pasting between chapters isn't pretty - especially if you end up changing the hierarchy.

In XML, all my topics were separate files. All I had to do was edit (or create)  component and book maps. DITA uses component maps and book maps to determine the sequence and hierarchy of topics. Did I mention sequence and hierarchy? Each of the topics is a separate object in the component map; I can move the object up, down, left, and right. Within the topic, I have a title, and maybe one or more headings. The headings are relative to the topic title. But the overall hierarchy (which titles are chapter titles, which are heading1, which are heading2, and so on) is determined by the topic's placement in the hierarchy.

Actually, the titles aren't really chapter titles, heading1, and heading2 - that's a relic of paragraph styles from unstructured FrameMaker or Microsoft Word. Transforms give the visual appearance in the output (such as a PDF) that mark chapter titles and help readers differentiate between heading levels in the hierarchy.

But, enough of the technical digression. The point is that it was really easy to reorganize this material in the XML authoring environment!  If I had still been working in unstructured FrameMaker, I would be cutting and pasting.... and changing paragraph styles for the headings. And, somewhere along the line, I'd probably make a mistake or two, and maybe lose track of where I was in the hierarchy.

What about the pain?

OK, I didn't move into a fairytale when I started writing in XML. I'm new to this environment, so I'm still coming up to speed. As I learn the new tags and the new processes, I'm getting faster.

The most frustrating part was editing my index. I'm used to FrameMaker, where I have a tool (IXGEN) that will pull all of my index entries into one editable table - even sort them alphabetically. Then, I edit the entries in one place, and can push the changes back out to my FrameMaker files. And without this tool, I was able to generate an index, click with a special key combination on the index entry, and get to my index marker.

In the XML authoring environment, I can only see the generated index in my output (in this case, a PDF). I can see index entries as plain text within the XML topic files, but most of my index editing happens when I see the entire index together and realize that I need to modify some terms to be more consistent with others.

If any of you know about great tools for developing and editing index entries in XML topics, please let me know!

Was it worth the pain?

Yes! There are lots of benefits of working in small topic files. It's easier to reorganize material. And it's easier to divide parts of the document between writers. I'm looking forward to the next steps, when more people join me in this environment, and we can start sharing content.

- By Michele Marques, Lead Information Developer, ITSM

• Video - showing the product in use
• Interactivity - using Flash or other technologies to add tutorial    elements
• Wikis and discussion forums - enabling customers to collaborate and    share information
• Proactive assistance - offering information for the current task,    without the need for the user to click a help link
• New devices to display information, such as PDAs and mobile    phones

I'm sure that there are other cool ways to provide information to users. Do   you have any examples of other ways to provide information?

Cool doesn't necessarily mean useful

As our users spend more time on Web 2.0 sites and checking web sites on   their mobile phones, does this change the way that they need to receive   information when getting help on software products? Do people who've grown   up on YouTube read manuals or online   help topics?  If not, perhaps we information developers need to adapt   to the new paradigm.

But to determine what's really useful, we have to look at what our users   need, whether in  manuals, help, or other product information. Where do they get stuck?   How do they process information? How will they find the information that   we're providing?

-by Michele Marques, Lead Information Developer, BMC Remedy ITSM

Hello! I'm glad that you found me at my new home on the BMC Developer Network (BMCDN). Write On is not just a stand-alone blog, it's now part of the BMCDN community. If you're a registered member of the BMCDN community, feel free to "friend" me.  This will make it easier for you to see what I'm writing.... but also means that I can easily find what you're writing. If you have a comment or question in one of the discussion  forums, I might reply in the forum - or be inspired to post a new blog entry on the topic.

As part of the transition, all my blog posts from talk.bmc have been imported. However, because Alena, who is managing this blog space, imported them, you'll see her name in the normal space for the author, and my name as text in the blog entry. Unfortunately, comments could not be imported with the blog posts.

Shortly after starting this blog, I wrote a post about two-way communication. I wondered if we would be speaking with each other, or whether I would be talking to myself.

Because I haven't received many comments, I felt like I was talking to myself, and wondered if more than a handful of people were reading. I checked the web stats, and found that more than a handful of you are reading my blog. My most popular pages seem to be:

• Could Facebook influence technical communication?
• Canadian Thanksgiving
• What does documentation mean to you?
• Documentation in an Agile Environment

Why don't you leave me a comment? Please let me know what you like to read.... and what you'd like to read about.

My posts about documentation, so far, have been focussed on documenting how software works. I talk about printed manuals and online forms of documentation.

Ronald Bartels pointed me to a page on his blog about problem management. When I check his posts about documentation, I see that while he is interested in the documentation about products, he seems mostly concerned with the documentation created by an IT department that is relevant to problem management - internally created documentation about how servers and other areas managed by the IT department have been set up, and standard operating procedures.

What sort of documentation do you work with?

I always like setting goals for the year, and then trying to meet as many as possible. When I was young, I would make long lists of all sorts of things I'd like to do - but it was impossible to get everything done.

Now I like to make goals that are achievable, but will improve on what I'm currently doing - or will help me reach long-term goals.

One of my goals for this year is to write more regularly in this blog. I'm striving for weekly entries, which should be achievable. If I make it a regular habit, maybe some weeks I'll write more entries.

I saw resolutions in other blogs:

• Write 365 thank you notes in 365 days
• Exercise and declutter the house (those should be mine, as well)
• Write and submit short stories (and related resolutions)
  

What are your resolutions for this year?