Skip navigation
Share:|

by Michele Marques, Information Developer Specialist, Digital Service Management

 

Augmented Reality is starting to become useful. For example, on a trip to Japan, I was able to translate instructions for a toilet into English. I opened Google Translate on my phone, and used camera mode to translate the image. If you didn't realize that a toilet might need instructions, check the pictures in this article.

 

The instructions didn't come with augmented reality - and I'm not sure how much I really wanted to visualize or explore the instructions. But the augmented reality side of Google Translate helped me bridge my illiteracy in Japanese.

 

This was a cool experience and made me wonder whether augmented reality is now ready for use as technical documentation.

blackzheep at freedigitalphotos.jpg

Image courtesy of blackzheep at FreeDigitalPhotos.net

  Here are a few links that I found:

 

What has your experience been with augmented reality?

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

by Michele Marques, Information Developer Specialist, ITSM

 

Sure, you might write great technical documentation. But if customers cannot find the information, your content isn't helping them.

 

Getting the information out there isn't enough, if the customer doesn't even know it exists.  There are lots of things to think of here: navigation, search, metadata. How does the customer find the documentation to begin with? Where are they looking? And what terms are they using to search?

 

Search terms

Your product might have a great term for a spiffy function. But your customer might not know that term, especially if they are new to the product.

 

If your documentation is on a web site, you might find out what search terms customers are using. Your admin might be able to provide that information. Or if you use Google Analytics, you can check both the Google search terms and the site search terms.

patrisyu at freedigitalphotos.net.jpg

Image courtesy of patrisyu at FreeDigitalPhotos.net

 

If you have a user community or user forum, how are people asking their questions? What terms do they use to refer to your product's spiffy functions? The experienced users might use your product's terminology, but the new users might use other terms.

 

Making search terms work

When you know the search terms, you can connect them to your content. Does it make sense to use these phrases in titles, headings, and other text? Tags or labels might make the relevant content more findable. If you don't want these terms to be visible, you can use metadata. Metadata is usually hidden from people viewing your content, but is part of the code that the search engines will use to index your content.

 

Getting from here to there

Sometimes the customer doesn't even know that she needs some content. For example, she finished installing the product, but doesn't know about a post-installation procedure. Or he found spiffy feature and doesn't realize that there is a related feature. That's where navigational aides can help.

 

Include links to related content, where to go next, and any other links that might help your customer get to the right location - or the next right location. Let each part of your documentation be a map to other content that the customer might want.

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

by Michele Marques, Information Developer Specialist, ITSM

 

When I first started writing documentation, the only time I had a chance to talk to customers was at the occasional user conference. I published documentation in printed guides and online help.

 

As I wrote in Are you talking to customers?, documentation teams now have more opportunities to talk to customers:

  • Forums and online communities, such as BMC Communities
  • Documentation feedback, such as comments left in pages in our online documentation and responses to surveys.
  • Social media monitoring

 

However, only a small subset of customers talk to us about documentation.  This feedback is very helpful. But what about all the customers who look at documentation and don't speak with us?

 

Because we have documentation online, we are able to use Google Analytics to get information about how our documentation is being used. We can get data to answer questions, such as:

imagerymajectic at freedigitalphotos.net.jpg

Image courtesy of imagerymajetic at FreeDigitalPhotos.net

  • What are our most viewed documentation pages?
  • How much time are people spending on specific documentation pages?
  • Where do people exit our documentation?
  • Over time, how does viewing of our documentation change?

 

All of this data is subject to interpretation. You don't have feedback to know exactly what the customers were trying to do, and you have to make guesses. For example, why is there a high bounce rate on certain pages? Perhaps you have context-sensitive help pointing to those pages, and customers get exactly the information that they need from a single page. A high bounce rate might be good in this situation. Or perhaps people are finding the page from a Google search or a referral, but they don't see useful content or links that seem useful, and they give up on the documentation immediately. In this situation, you might need to improve the quality of your pages.

 

Are you using Google Analytics or other analytic tools on your web-based documentation? What data do you look at?

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

- By Michele Marques, Information Developer Specialist - ITSM

 

A growing number of companies, including BMC at docs.bmc.com, use a wiki to provide customer-facing documentation. It's easy to author information, and it's easy to copy a page as the starting point for a new topic.

 

As an author...

  • When you reuse existing content, you don't have to write that content. Someone else did all the heavy lifting. Or maybe you wrote that content previously.
  • You benefit from reviews and edits on the reused content. The reused content should be reviewed in the new context, but this review might be quicker.
  • If you reuse content, you can automatically get the updates made to the reused content. For example, if you are responsible for the source content and correct an error, that same correction is applied wherever the topic is reused. If a customer leaves a comment asking for clarification, you can make the clarification once, and the clarification applies wherever the topic is reused.

 

For readers....

When content is reused, readers get the advantage of consistency - the same information appears exactly the same in all locations. For example, if several products use the same reporting console, the general information about how to use the reporting console would be identical. If the content was not being reused, it might be different - and the reader might be left wondering which version was the most accurate or the most complete.

 

Can you reuse content on the wiki?

Reuse is common in DITA authoring environments, but other tools also allow reuse. Whether you can reuse content in a wiki depends on what wiki you're using. Confluence wiki has features to reuse an entire topic (include) or excerpts of a topic (multi-excerpt include).

 

Who can reuse my content?

Anyone authoring on a Confluence wiki can reuse any content on that same Confluence wiki instance, and will get the benefits that I mentioned above.

 

Other people are able to copy and paste from the wiki, or export wiki topics to XML or Word formats. This doesn't provide the benefit of automatic updates, but you can sign up for notification when topics are updated. However, do keep in mind that all content on docs.bmc.com is copyright by BMC.

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Michele Marques

Looking back on 2014

Posted by Michele Marques Employee Dec 22, 2014
Share:|

by Michele Marques, Manager, Information Design and Development (IDD)

 

As we approach the end of the year, it's a natural milestone to pause and look back over the past year. For me, some of the highlights of the year included:

 

On a personal level, the highlight of this year was my trip to Japan.

B5N-jvECIAA3hs9.jpg

What were some of the highlights from your year?

 

I hope that you all had a wonderful 2014 and that 2015 is even better!

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

by Michele Marques, Manager, Information Design and Development (IDD)

 

Have you noticed the new BMC Community for BMC Product Documentation?

 

Back in October, I asked "Are you talking to customers?" Information Developers at BMC engage with customers in the BMC Communities for our products. We can find out about customer questions and challenges, and see the tips that they share.

 

Recently, we started the BMC Product Documentation community as a place for customers to ask questions related to documentation, suggest ideas for improving BMC documentation, and collaborate with us. Engaged customers have joined in from the start. I'm looking forward to finding out more about their documentation needs.

 

I hope that you'll join the conversation.

1.png

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

by Michele Marques, Manager, Information Design and Development (IDD)

 

From time to time, I look at the number of views for my blog posts. I want to see what interests you. My ten most popular blog posts are:

Blog postWrittenNumber of views
BMC Remedy 8.0 documentation now available at docs.bmc.comOctober 201210469
Tuesday three-by-three: techcomm posts and linksJune 20113793
Don't just read on -- write on!January 20103744
Video tutorialsFebruary 20102999
Could facebook influence technical communication?September 20072858
How do you define documentation?February 20102233
Reusing content on a documentation wikiJanuary 20122147
BMC Atrium Core 8.0 documentation now available at docs.bmc.comOctober 20121890
What do you expect from a documentation wiki?May 20111862
Cool news about ITIL® and BMC SoftwareMay 20091795

 

What do the numbers indicate?

My most popular blog post by far isn't even in this blog. It's the product documentation announcement that I wrote in the blog for the BMC Remedy Community. I'm not surprised there are many people interested in the BMC Remedy product. I'm more surprised that I wrote some posts that are more popular than another product documentation announcement.

 

With only one exception (Don't just read on -- write on!), all my other popular blog posts have stuck to the overall purpose of this blog (exploring new directions in technical communications). Probably a sign that only a few of you will be reading this off-topic post.

 

Other factors contributing to some posts being less popular

  • Even old posts get a few views every month. It might take time for my recent blog posts to build up numbers to make it to my top 10.
  • I haven't been blogging regularly for the past couple of years. It's mostly people who blog on a regular basis who have a regular following.

 

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

by Michele Marques, Manager, Information Design and Development (IDD)

 

Time management advice often includes tips for spending less time in email. If you get lots of email, like I do, it's easy to spend too much time responding to email.

 

I agree that it's necessary to limit the amount of time spent in email. Some people only check email at certain times of the day. I am more flexible about checking email - but I limit my time and don't let myself get bogged down in email.

 

I have seen advice to keep my inbox clean. I understand the logic - you don't want to keep reading the same email over and over. However, I find that if I spend time filing all my email into folders (and responding immediately to quick emails), I am:

  • spending too much time filing email
  • not always sure where I filed email, and then spending too much time finding it again

 

My approach won't work for everyone. I admit that I use an Outlook feature that is present only in their desktop client. However, if you use another email system, you might be able to find an equivalent approach that works for you.

At Sign by ponsulak freedigitalphotos.net.jpg

Image courtesy of ponsulak / FreeDigitalPhotos.net

When I triage email, I don't reply

When I triage email, I quickly scan through email subject lines. First, I open calendar invites, so that my schedule is up-to-date. I do accept (or decline) invites, as I just have to press a button. Then, I open email messages that I might have to deal with (read for information, reply, or take action).

 

At this point, I don't reply to emails that take more than one or two words. If I have to stop to think about my response, it might take too long to triage emails. 


I set a task for every email that requires an action or reply

I use the "Followup" feature in Outlook. For anything that requires a reply (without action) or that must be dealt with soon, I flag it for "Today." If an action is required, I might flag the followup for a future date. Anything that I flag for followup appear in my task list, which I display next to my Inbox. I have set up color-coded categories to indicate the priority and time-sensitivity. I used to apply both categories to all items, but I now only apply the categories to the most important and/or time-sensitive items. These color codes help me figure out what to work on next in my task list - in case I cannot get to everything in the day.

 

If an action will take some time, I'll usually put the time on my calendar. But, I might only schedule that time when working through my task list.

 

By taking this approach, I can limit the amount of time triaging email. I don't worry about keeping a clean inbox, because every email that I plan to act on has a flag. If I won't have enough time to triage all my email (for example, after vacation), I might open a smaller percentage of emails. I might not open all the email messages, but I'm also not afraid that I cleaned out a message that I should have dealt with. There is the option to later come back to messages.

 

In a big email discussion, I only flag the specific message or message to which I want to reply - and I don't delete email messages to which I might want to come back. This means that my Inbox is a repository of messages of temporary value.


I file emails that I need to keep

If I need to keep an email, I file it in the appropriate folder. If I won't need to keep an email after I deal with it, I leave it in my Inbox.


I clean out my completed task list

At the end of the week, I open my completed task list. Then, I delete all tasks that are in either my Inbox or my Tasks folder. I leave messages that are stored in specific folders.

 

How do you manage your email?

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

by Michele Marques, Manager, Information Design and Development (IDD)

 

When I first started writing documentation, the only time I had a chance to talk to customers was at the occasional user conference.

 

Things have changed, and now as an information developer (technical communicator), you have a lot more opportunity to speak with customers - at least online.

 

Forums and online communities

Information developers at BMC are fortunate that our BMC Communities are active. Every day customers are asking questions about our products and sharing tips.

 

If you spend some time in the community, you can find out what's important to customers and what they are trying to do. You can update documentation, so that it answers their questions. You can prioritize the important areas of documentation to focus on.

Call Me Geture by imagerymagetic freedigitalphotos.net .jpg

Image courtesy of imagerymajetic / FreeDigitalPhotos.net


Documentation feedback

Customer conversations in forums and communities typically focuses on the product itself. You can provide channels for customers to give you feedback specifically about the documentation. With web-based documentation, you can let customers leave comments on documentation topics, and can link to a contact form. If you provide PDFs or print documentation, you can provide an email address for feedback.

 

Social media

Your customers might be on Twitter, FaceBook, or other social media talking about your product. If your company has an official Twitter account or FaceBook page, you can follow it and see how customers respond. Try doing a Twitter search for your product to see what people are saying. However, before you start responding, check your company's social media policies.

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

Guest blog post by Deval Faldu. Deval is an intern working at BMC Software. She has a diploma in technical writing and a management degree in Finance. Her personal interests lie in reading books (strictly fiction - or non-fiction, if strongly recommended), watching movies, and listening to music.

 

Conference volunteers and presenters from One BMC.

 

22nd June dawned a beautiful day squashing all our fears of heavy rain that might have affected the participation at the STC Pune Zip conference 2013, hosted by BMC Software, at Pune. We were delighted to see a huge number of participants already assembled at the entrance for the registration before time.

 

Around a hundred people attended the conference that included documentation managers, senior writers, mid-level writers, and aspiring writers. It was deemed as the biggest gathering of technical writers at a regional level.

 

Tarun Sharma (Senior VP and Head of BMC India and Ukraine) welcomed all the attendees in his opening speech. Little did we know that Tarun himself is an author of technical books and his affection to technical writing surprised all of us. He graciously offered BMC Software premises to host all the subsequent STC conferences.

 

Jaya Choudhary’s session threw light on the intricacies of documenting in a Lean Model Software Development, a world apart from the Agile Methodology that is followed in BMC Software, in a short span of 20 minutes. The Lean Model Software Development eliminates the waste at the end of every TAKT (the Lean term for a production cycle). This methodology is in contrast to the Agile methodology, which breaks down the work into time-bound iterations, where the product is usable at the end of each iteration.

 

Jaya’s session was followed with an introduction to open source software from a documentation perspective by Aakansha Singh, who helped us understand the different styles of documentation practiced in the open software industry. This session was particularly interesting for the BMC IDD team members, as the IDD team was not previously exposed to developing documentation for open source tools.

 

Paresh Naik’s session on What the Manager Really Wants from You was based on a book by R Gopalkrishnan on What the CEO Really Wants from You. Paresh invited all the managers attending the conference on the stage, and the participants threw a volley of questions at them to decipher what managers seek from their colleagues. Prachi Karnik won a copy of the book What the CEO Really Wants from You, from Paresh for asking the best question to the managers.

 

Nabaneeta Sarkar enlightened us with different types of videos and their uses. She took us through a journey of various videos that we can create. She stressed the importance of organization’s need for having a content strategy for videos.

 

The Zip conference was packed with a lot of demos for various tools useful to a technical writer. Mira Balani demonstrated the use of Microsoft Project, a powerful tool for tracking projects and releases followed by a demo on Madcap Flare by Prachi Karnik. Aakansha Singh and Neelam Shendye conducted a workshop on Publican, an open source, command line, XML-based authoring tool.

 

Abhijit Wakhare conducted an interesting session on documenting in an uncertain environment.  A lot of his points resonated with daily challenges faced by a technical writer.

 

Ramesh Aiyyangar (President, STC India Chapter) and Frederik Menezes provided an update on the STC India activities.

 

The sessions were concluded by Makarand Pandit demonstrating 5 power tools: Speech-to-text, Drawing Tool, eBook Creator, PDF Protector, and ePUB Editor in a matter of 25 minutes.

 

Paresh Naik from BMC concluded the conference with a vote of thanks to all the participants and also thanked STC for giving BMC the honor of hosting the event. All the participants praised the efforts put in by BMC folks to make the event a success. The BMC folks in black t-shirts also made a lasting Impact.

 

To quote a few participants on their experience:

 

As soon as we reached, we were really impressed with the hospitality BMC offered us, right from parking the vehicle till taking our seats. BMC gets a 10 on 10 there.” – Manash Baruah, on his blog.

 

What is more important is BMC has expressed its willingness to host such events in future too. This is a great example for other companies to follow suit. Kudos! BMC.


Awesome is the only word for all organization, team spirit, and all the courtesies extended to the participants.” – Ramesh Aiyyangar, STC India President


From the day we started discussing the idea I knew that I could count on BMC’s team. The overall conference feedback reinforces my sentiment. Participants were extremely happy with the arrangements and many even envied the infrastructure and the team spirit.” – Makarand Pandit, STC Pune City Representative


The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

by Michele Marques, Associate Manager - Information Design and Development (IDD)

 

For those of you developing technical communications, how technical are you? People come to technical communications with all sorts of backgrounds. Some people (like me) start with a programming or IT background and feel comfortable with technology. Other people start with an English or other non-technical background, and develop technical skills along the way.

 

Sarah Maddox recently blogged about Python as a useful tool for technical writers. She includes a couple of examples of how she automated tasks with Python.

 

If you're not ready to tackle Python, and you use Microsoft Office products, macro or VB scripting can be a way to ease into scripting. For example, if you have a repetitive task in Word or Excel, you can record a macro. Recording the macro creates a script that you can then edit.

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

by Michele Marques, Associate Manager - Information Design and Development (IDD)

 

In my previous post, I mentioned that I'm using Buffer to measure how many people click the links that I share in Twitter. I shouldn't really be surprised, but I got far more clicks for three fun videos than for anything else.

 

Is everyone on the internet only interested in Fifty Shades of Gray, Harlem Shake videos, and cats?

 

Although I got many clicks on those videos (especially relative to my number of Twitter followers), I didn't gain followers. Trendy and fun topics and links might lure people to check a Tweet and follow a link. But if they're not interested in the topics that I care about, those people won't stick around.

 

Have you been successful leveraging trends to reach out to people? If you have, please share your tips.

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

ID-10023069.jpg

Image courtesy of Carlos Porto / FreeDigitalPhotos.net

Share:|

- By Michele Marques, Associate Manager - Information Design and Development (IDD)

 

 

Whether in technical communication or social media,  many people might read your message, but only a few respond.

 

Quantifying influence

Previously, I asked, "How do you measure influence?" At that time, I was starting to play with Klout. My Klout number is a measurement. And I can see it go up or down. However, I cannot fully see what's going into my Klout score, so I don't fully know what it's measuring. Even if I could see the formula, my Klout score might not be that useful - because it is one score that covers various factors.

 

In addition, the score might miss important factors. Klout can measure who is reacting to my Tweet or post by replying, mentioning, or retweeting. But Klout doesn't measure how many people following the link. Klout seems to measure how I engage people in conversation more than how I influence them.

ID-10075924.jpg

Image courtesy of David Castillo Dominici / FreeDigitalPhotos.net

 

Have you tried Kred, another tool for measuring social influence? Or any other social influence tools. You might get different results from what you get on Klout.  I'm finding minimal value from a single number, but perhaps there are better tools.

 

How many people view your message?

Depending on the medium, you might be able to see how many people view your message.


MediumHow many people view my message
Web-based documentationJust as for any web site, there are analytics tools available that can tell you how many times a page (or topic) has been accessed within a given time period. You might be able to get more information, such as unique visits, location of visitors, search terms to find the page, and more.
Blog postsBlog sites typically offer a portion of the analytics offered by web site analytics. On my blog here, I can see how many views each post had. In the past couple of years, most of my posts had around 300 views. When I blogged more frequently, most posts had 500 - 700 views. Several of my blog posts had over 1,000 views.
TwitterYou can see how many followers you have, but most people probably didn't see any specific tweet. Tweets get lost in the stream. People only dip into Twitter periodically, or they only check their Twitter lists. And someone could be reading your message from a Twitter list without following you. You can see how many lists you're on, but that still doesn't tell you how many people are reading your tweets.
FaceBook, Google+, and other social networksSimilar to Twitter, you can see how many people signed up to receive your posts (friended you, added you to a circle, and so on). However, you only know that someone viewed the message if they responded (comment/reply, like, share).

 

How many people act on your message?

Measuring this depends on your call to action.

 

For technical documentation, you might be helping people perform a task or troubleshoot an issue. Your call to action contains steps to follow. You probably won't know if people are following your instructions. Analytics might tell you how long people remained on the page. And if you link to next steps, you might be able to tell how many people followed the link to those next steps.

 

For blog posts, Twitter, and other social media, you likely have other calls to action. If you're trying to get information from your readers, how many replies do you get? If you are directing people to linked information, use link shorteners (such as bit.ly or buff.ly).

 

Recently, I started using Buffer for tweets where I share links.  It's interesting, but sometimes a bit depressing to see which links are the most popular. Most links get no clicks. Some links get a handful of clicks. If 10% of my followers click a link, I feel that I'm sharing what interests them. However, the links that get by far the most clicks are light-hearted, such as a link to the day's Google Doodle.

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

- By Michele Marques, Associate Manager - Information Design and Development (IDD)

 

Looking back on 2012


2012 has been a busy year for me and for my team. For the BMC Remedy IT Service Management Suite 8.0 release, we released our documentation on docs.bmc.com. Customers leave comments on documentation topics, and my team makes updates to improve the usefulness of our documentation. My team loves the opportunity to interact more with customers. If you're a BMC customer using our documentation, we hope you'll leave comments - let us know where you have questions, where you have constructive criticism, and what you'd like to see more of.

 

I wrote a blog post about the BMC Remedy 8.0 documentation in the BMC Remedy community. And I helped the BMC Atrium IDD team get a blog post out about the BMC Atrium 8.0 documentation in the BMC Atrium Platform community. We're also getting the word out on @bmcdocs about our documentation. If you're a technical communicator, how do you get the word out about your doc updates?

 

Sadly, I didn't write much in this blog in 2012. Just three posts:

 

Goals for 2013


I'm hoping to blog more in the coming year - but I'm not sure that I'll become an avid blogger. Some people seem to write blog posts quickly. They write an entry every day - or sometimes several in a day. I find that I usually need an hour or two to write a blog entry. How long do you take? What are your tips for getting out blog posts more regularly?

 

I'm reasonably active on Twitter. For 2013, I'd like to be more focused and less random. I set up a couple of new lists - a TechComm list to follow technical communicators, and an Industry list to follow people in my industry (itsm, ITIL, and business service management).

 

What are some of your goals for the coming year?

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Share:|

- By Michele Marques, Associate Manager - Information Design and Development

 

It's easy to get stuck in a rut, and not even notice that you're stuck. In his post on The Design Implications of Tool Choices, Mark Baker writes, "When we move to a new tool, therefore, we often expect to keep the same information design and the same presentation and formatting style as we had with the old tool." For example, technical communicators used to working on books might try to replicate the experience online with a table of contents, index, and topics arranged in a narrative flow. 

 

When I try to think about new directions in technical communication, often I find myself thinking about current challenges. It's easy to think about incremental changes.

 

How do you break free of old paradigms?

Sometimes, I look to areas outside technical communication for inspiration. For example, I once looked at how facebook could influence technical communication. Other times, I look at trends that are just starting to his technical communications, such as gamification. (Here's an interesting video of a presentation about gamification and technical communication.)

 

What about science fiction?

Recently, I've been wondering if that problem is that I'm only considering what I know can be done. Maybe I should take a science fiction approach and think about what technical communication could be like in 20 or 100 years. I don't remember seeing anyone in Star Trek looking anything up in a manual, but they certainly asked the computer for help.

 

 

The postings in this blog are my own and don't necessarily represent BMC's opinion or position.

Filter Blog

By date:
By tag: