Subscribe to RSS
Posts Tagged ‘online help’
Can online help show “read wear?”
I’ve been re-reading Jakob Nielson’s Participation Inequality essay on useit.com, and the suggestion to some how show wear marks on content struck me this evening for some reason. I guess it’s because I’ve been working on Drupal recently, and discovered that Drupal documentation contains site recipies in the Drupal Handbook. What a nifty idea. Stick with me, these two concepts are related through a recipe and cookbook angle.
Part of Jakob’s treatise on inequal participation in online communities is that you can do little to overcome the typical contribution stats of 90-9-1, although one of the suggestions is to make participation so easy that you don’t even know you’re contributing. Case in point - Amazon’s “people who bought this book, bought these other books” recommendations. Sounds like the easiest contribution ever - data mining and analyzing, then giving the data back to the shopper in an understandable format.
Jakob says, “Will Hill coined the term read wear for this type of effect: the simple activity of reading (or using) something will “wear” it down and thus leave its marks — just like a cookbook will automatically fall open to the recipe you prepare the most.”
What are some similar examples of displaying read wear from the online help or user assistance world? The first example that comes to my mind is a wiki’s “most active pages” feature that shows the page with the most edits. However, the page with the most edits may be more controversial than truthful, so the most popular pages would be more useful than touting pages most active.
How else can you show read wear on a website? You could also show the most searched-for terms when the user searches. Concepts may be more easily connected when you understand what others were searching for.
Or, rather than showing search terms, show the most recently viewed knowledgebase articles or most popular articles. I know I’ve found that useful in the past when searching through BMC Software’s rich knowledge base.
Just like CNN and other news sites offer a listing of the most emailed stories per hour, you could show the most emailed online help topics if your system offers the ability to email topics.
The ability to rate an article is included in many online help systems, and exposing the ratings to the reader would help in determining how “well-worn” a help topic is.
Tag clouds can display read wear as well, as I just realized while looking at the Wordpress FAQ starting page - tonight, the largest tag is “Images.”
I’ve distilled it down to popularity, time spent on the page, rating on a page, and number of edits from strongest to weakest indicators. What other factors matter in an online help system?
Wiki as online help source
A response to the question, Wiki-to-Help? on the Help Authoring Tool Yahoo Group.
One of our test engineers (and the lead developer of our company wiki) just approached me with the idea of using our company’s internal wiki as the central repository for all company material and using it to generate online help.
I’m following the discussion with interest. I, too, had a similar question asked of me from a developer when we were working in an Agile development environment at BMC Software. In that case, which was at least three years ago, the matchup between the wiki HTML output and the HTML output I needed for our particular help system just wasn’t a good fit. But today, there are better pairings, input to output. I think it’s feasible to go from a wiki to an online help system. It really depends on what output you need, and what you’re willing to do to ensure that the wiki source is worthy of publishing (tested, vetted, trusted, and so on).
I’ve been working on wikis as source for manuals, where the output is a PDF file. In general, yes, wikis are a little clumsy to work in for authoring. For example, some wikitext doesn’t understand that you want a numbered step list with images in between each step and that you want the numbering to continue after each image. So if you’re accustomed to a nice HTML authoring interface, a wiki authoring interface will “feel” like a step about 10 years back in time. 
On the more interesting issue, the cultural issue (or the career issue, depending on how you think about it), I think the basis of most arguments against using wikis as source is the fear of loss of authoring control. See wikipatterns.com for the many anti-people patterns that wikis tend to foster if you don’t take steps to avoid them. I especially liked one of the responder’s comments to the list that he didn’t want to become an editor for a wiki. I think he’s right - that “magazine editor” is one of the roles you could take as a wiki-based author. You could also consider your role to be “community director” if you think you can motivate others to contribute to your wiki that will eventually be the help system. There are different roles that will evolve, and it’s up to you to figure out what role might work well in your environment (or if it would work at all). I wrote up a blog post last week about determining where your role as technical writer is most valued in the company, and building from that role.
I believe the cultural or social difficulties are the more difficult hurdle - you have to ensure that the community surrounding a wiki (those that can and will edit) is a group that is willing to work together and collaborate towards the common goal of publishing a customer-facing help system from the wiki. In a SXSW Interactive session titled “Edit Me! How Gamers are Adopting the Wiki Way” one panelist said that a core group of five editors on a wiki may be the best practice for the size of the group. This type of small number is represented and described in the 90-9-1 theory on wikipatterns.
A solution that might help you wrap your arms around the wiki as source is to set aside only one area or category of the wiki as the articles from which the online help gets generated. Again, without knowing the wiki engine you’re working with and the types of output you’d require, it’s difficult to know if a “wikislice” solution could help in your situation.
Anyway, I could go on and on (and I believe I just did go on and on) about using wikis as source for end-user documentation. I’m pleased that Sarah O’Keefe has just published a white paper titled “Friend or Foe? Web 2.0 in Technical Communication” that should be helpful as we begin to define our roles in each company and how we integrate user-generated content with our own on our product’s web sites.
I hope this information can help you build an argument for or against the use of wikis as source for online help. Please let me know the eventual outcome, and I’d love to hear your thoughts on my response.
Can DITA train writers? Or does it require too much programming?
DITA for writers (content creators)
I just did a search on amazon.com for books for beginning technical writers and also to investigate what books are being written for our profession and for others wanting to start in our profession. I came across a book called Writing Software Documentation: A Task-Oriented Approach that suggests three categories for writing:
- writing to teach (for eager learners)
- writing to guide (for reluctant users of the product)
- writing to provide a reference (for experts who need only occasional support)
I immediately saw a connection to the three content types that DITA prescribes:
- concepts to teach understanding
- tasks to guide performance
- reference to offer facts or lists of information
Because writers have to immediately place the information they want to record into one of these three types of information, they are being trained on how to write in a task-oriented, performance-based manner, via DITA. I am especially interested in this “training” for wiki authors and talked about the idea at our recent presentation at the Central Texas DITA User Group meeting.
DITA for publishers (formatters)
Recently a few techpubs bloggers have been talking about DITA and its weaknesses, such as a lack of online help outputs, and how difficult it can be technically if you don’t already have a staff with pseudo-programming skills. Gordon Mclean writes “DITA is not the answer” and I think the question he is trying to answer is, “what is a single-sourcing tool we can use in our environment (which includes Technical Communications, Training, Pre-Sales and Marketing) with our current resources?” Instead of DITA, it looks like he’ll go with Author-it.
Since I just this past year moved from BMC, which is still moving to DITA, to a small techpubs group that uses Author-it, I can understand his reasoning and agree with his business case assessment. The toolchain for DITA is very nearly there, but often a CMS-based approach has too much overhead for small companies. It can be cost overkill when you have few topics to contain.
Scott Nesbitt followed up with his post, “DITA’s not THE answer for single sourcing.” I think he’s spot on with the analysis “it’s difficult to get good PDF or online help from DITA without extensively customizing XSL stylesheets or passing DITA source files through tools like FrameMaker, Flare, or WebWorks.” One of his commenters said something about consultants smelling blood in the water, yikes. In other words, I think he meant that XML consultants knew how much customization would be desired and can have a feeding frenzy on the potential work possibilities. My guess is that the people who have been around XML for years know that there are still basic needs for output, and their experiences have shown them that nothing that is structured is an “out of the box” experience. So much of the success depends on your content to begin with.
I’ve found the same conclusions about the output in my experience. When you dig into single sourcing, be it with DITA or another tool (Madcap Flare, Author-it, FrameMaker, RoboHelp, and the Adobe Technical Communication Suite) the real business-case killer seems to still be, where can I get pretty PDFs that are formatted just as I like them? With DITA, one answer is to go get the Mekon FrameMaker plug-in for the DITA Open Toolkit. No XSLT-FO knowledge required.
People love their tools to get their pretty PDFs or sleek online help systems. Plus, so many of the employers out there have a lot of content that looks pretty nice already in a specific tool. The legacy documentation may be one reason why hasn’t DITA helped our industry get away from tool love. Tech writers and their employers fall in love with tools. I’m not saying Gordon or Scott are tool lovers, but certainly some people they’re hiring will be. There is probably also an element of “if it ain’t broke, don’t fix it.”
DITA for all?
Sarah O’Keefe has a thought-provoking analogy in her comments on her post signed “DITA Dissident.” The analogy is that creating desserts using a frozen pie crust is one method of getting results. If a pretty PDF is your ultimate dessert, then for some, DITA is a bag of flour, meaning you’d better be a skilled baker if you’re going to use it for the best pie (PDF) ever. For others, DITA is a frozen pie crust that makes a perfectly good cherry pie (PDF) or apple pie (plain HTML) or chocolate creme pie (Eclipse help). Although isn’t the filling the content and the pie crust the DITA map?
Their conversation first started with Eliot Kimber discussing DITA’s use for narrative documents. Alan Porter talks about DITA use for narrative writing as well, but in a different line of thought in his post, Is DITA Just a Story?
All the posts I’ve linked to are enjoyable for me to read and to point to and to think about. I’ve read it before, and I’ll say it again, I believe along with others that DITA has the potential to transform our industry. Just last night I said to the San Antonio STC group, today we all speak HTML tags pretty fluently. In ten years, will we all speak DITA tags just as fluently? “I wrote the shortdesc according to the guidelines and it works for the topic, but I am not sure if my conref target is going to be there every time. I guess I should rewrite the concept topic.” Heed the warnings and experiences of others before making the leap to topic-oriented single-sourcing or your expectations and those of your customers may not be met.
Q and A about Author-it and DITA - guest post from Mike Stockman
I read this recent conversation on the author-it-users Yahoo Group with interest. I haven’t had a need to author DITA topics with Author-it, so I have to rely on others for information on how it works. With Mike Stockman’s and Tony Watkin’s permission, I’ve written their Q&A as a blog entry.
Tony: What are your experiences with using Author-it for DITA output?
Mike: The DITA output is partial. That is, they don’t support a lot of DITA features, so that most table definitions are not passed through, bookmaps aren’t supported (although ditamaps are), reflinks aren’t supported, syntax diagrams aren’t supported, and so on. However, it’s definitely usable, so that AIT puts out the four DITA topic types (task, reference, concept, and base) properly structured, index entries are supported, tables and images are handles correctly, and so on. The best test would be to publish to DITA and see whether the results are what you’re expecting.
Tony: Is there a mechanism provided by AuthorIT for being able to search within the DITA XML generated output afterwards from within the browser when accessing the DITA output directly from the browser (i.e. not via AuthorIT)?
Mike: There is no mechanism provided by AIT for viewing DITA output. Once you have the DITA output, you can either view the XML code, or transform it into something more viewable, such as XHTML or PDF. Grab the DITA Open Toolkit, available at <http://dita-ot.sourceforge.net> for all of the tools you’ll need to transform the DITA into something else.
Tony: Also, does AuthorIT just output XML when publishing DITA or does it also produce corresponding XHTML?
Mike: AuthorIT publishes DITA by first publishing to XHTML, and then transforming that to DITA. It does not, however, leave the corresponding XHTML behind, so you can’t view it. Your choices for viewing XHTML would be to either publish from AuthorIT to XHTML directly, or transform the DITA to XHTML.
Mike’s final comments
AuthorIT’s DITA is not a fully-developed DITA solution, so don’t expect it to be. Instead, AuthorIT’s DITA output is great when you have a need for single-sourced output to multiple formats, such as if you needed Word, XHTML, *and* DITA. Where I work, for example, we use AuthorIT’s Word output for our printed docs and PDF, and use the DITA output to create our online help. If you need the advanced features of DITA that AuthorIT doesn’t support, I’d suggest going to an all-DITA authoring environment and avoid AuthorIT altogether.
Embedding video in your online help
More note taking at sessions at the Quadralay WebWorks Publisher RoundUp. This session is with Stephanie Cottrell Bryant, author of Videoblogging for Dummies. She’s an ePublisher user who embeds video demonstrations of software within online help.
Customers love video embedded in the online help. Time saving for them, and no need to attend a training class. Her customers love it, love it, love it.
Tool kit she uses - Camtasia studio, Framemaker, and WebWorks ePublisher.
Need a script - but you might already have it, like a list of steps in a task.
Annoyance - don’t take your whole desktop while capturing screencasts. “Your desktop icons are like seeing your underwear on a clothesline.”
Also, don’t show the time of the day (like 4:00 AM) that you captured the screens, it’s sort of too much information.
Sizing of about 320 by 240 is about the right size for YouTube. Or 480×360 if you need something slight larger. If you’re delivering the video on a hard drive (installed as part of your product), you can make it even bigger. But for Internet or CHM deployment, keep it small.
Record audio first, then replay the audio while you record the video - the timing will be easier to get synched up.
She likes to use a “highlight click” feature that shows a subtle red circle showing where you click on the screen. She also modifies the cursor so that it’s larger and a yellow color while capturing the screencast.
She “cropped” out the first part of the video where she moved the screen around to the optimal location.
She recommends Flash for video output (.swf file). But if you know people are using Windows, you can make Windows Media files. If you know they’ll only be played back on an iPod, make a QuickTime file. If you want to send these video files to someone else and they don’t have Camtasia, save them as AVI - they’ll be larger files but the recipient will be able to compress them as needed and make another format. Also, any video editing software can edit AVI files.
If you want to use embedded video within an HTML file, don’t use Flash, however.
Goes into Frame, creates relative path to the movies (which is in Files folder within the ePublisher directory system), then generates the HTML using ePublisher.
She uploaded javascript to the WebWorks wiki that writes the embedded video code in on the fly, so that Internet Explorer doesn’t put a popup in front of the user, complaining about the embedded object.
In the javascript call to the video file, she’s adding an extra 10-20 pixels to the height dimension so that the player bar shows up at the bottom.
She uses conditional text in FrameMaker called “Passthrough” for all her javascript code so she can put it right into her FrameMaker file.
How to create help files for custom BMC Performance Managers
All this is documented in the Controlled Availability release of the BMC Performance Manager Software Development Kit (SDK), but I thought I’d write it up here as well, hoping it’s helpful. Contact your sales rep if you want more information about the SDK for BMC Performance Manager.
BMC Performance Manager is a product with the ability to be extended, allowing you to write your own custom monitoring tools, called Performance Managers. If you write a custom Performance Manager, you’re going to want a help system to go with it, so that your users know which parameters are monitored with your tool. And if you want your custom Performance Manager to be certified by BMC Software, a help system is required. Here’s an overview of writing that custom help system including sample files.
- Write an HTML file for each application class and the parameters within that class, nested like this set of sample HTML files for the BMC Performance Manager for Citrix Presentation Server . For example, the farm application class contains parameters like “logged in users” and “disconnected sessions,” with each parameter documented in separate HTML files. These files contain Dreamweaver template code but should be useable with any HTML editor.
- Place your Help content files in your Performance Manager Maven project in the following location: …/META-INF/help/browser_help/.
- Open your application definition XML file and add these Help elements in the application definition: help-group-definition or help-group-reference, and help-item. You need unique attributes msgkey and name on both these elements. Here is an example code snippet:
-
<application-definition name="patsdk-ri-service"> <display-name>Reference Implementation Application</display-name> <description> Instances of this application-definition can be used to monitor the availability of many common network services such as HTTP, Telnet, FTP, etc.</description> <help-group-definition msgkey="riapp.intro.displayName" name="intro"> <display-name>Patsdk RI Application</display-name> <help-item msgkey="riapp.intro.about.displayName" name="about"> <display-name>About</display-name> <file>riapp/about.htm</file> </help-item> </help-group-definition> <help-group-definition msgkey="DRCIT-Farm-Container.desc.book" name="DRCIT-Farm-Containerbook"> </help-group-definition>
- Add Help-related fields to your project.properties file (located in your Maven project folder). There are a couple of commented lines that you can uncomment by deleting the # sign at the beginning of the line. Set solution.product.code equal to your PAR file name (without the .par extension), and use a sample category such as database, networking, etc.
-
solution.product.code=PRD solution.help.category=networking
- When you build and deploy your Performance Manager, the .htm files that you created are compiled into cross-platform browser-based help. These files and the Help content are packaged in a .jar file which is then put into the .par file and deployed to the BMC Portal Help repository server. Automagically.
Sounds pretty straightforward, and we’ve done this internally for a few Performance Managers already, which is why I wanted to share some sample files with you. Let us know how it works for you.
