Less really can be more
by Gloria McConnell
Welcome to the “Back Page,” a column presenting the editor’s thoughts on all things tech. comm.
It seems like I have been in a time crunch forever. I’m sure it is true for you, too. Whether it is at home or at work, the time to do all of the things I want to do, or to do them the way that I want to, just does not exist. I have long given up any perfectionist tendencies (that very phrase makes me laugh with an on-the-edge tinge of hysteria), and settled for “it is good enough,” well, it is better than it was,” “it will just have to do,” or “too bad, it will have to wait.”
For quite a few years in the world of information development, my first question has been, “How can I serve the user and still meet my deadlines?” One answer I’ve found is to really challenge two notions that many information developers hold dear: the notion that because a tool has a particular functionality, we should use it, and the notion of completeness for completeness’ sake. Here are two outstanding examples:
- A FrameMaker book that included more text inset files within its chapter files than it did chapter files in the book. And text insets within text insets!
- A RoboHelp HTML Help project overburdened with “helpful” hyperlinks.
Text Inset Insanity
This migraine began with an admirable goal in mind? separate text files would be used for information and procedures that were common to the installation and upgrade guides for three separate products. The files would be imported into separate chapters within the different books. Single sourcing is a good thing, and Adobe FrameMaker allows a file to be imported into a chapter file such that it is treated as part of the chapter.
What could be the problem? This is a difficult case to explain, but I will do my best. As the products went through new releases, the understanding of what should be “single sourced” became muddied. Specific needs and conditions arose, and the solution was to create more and more text inset files to deal with them all.
No specific person, such as an information architect, kept tabs on the information to determine whether it should be handled as a text inset or integrated into the main chapter files. No one established basic content guidelines, for that matter (for example, in some cases the heading was included in the main chapter and sometimes in the text inset). Multiple writers worked on these documents, and I’m sure that they each did their best. But without any oversight, or time to re-evaluate and correct the problems, file management issues and the limitations of FrameMaker overtook any benefits that may have initially existed.
The new information developer assigned to the project for the current release found himself mired in a plethora of problems, most significantly, creating and maintaining cross references. It turns out that FrameMaker is very persnickety about cross references to content within a text inset. The information developer spent 90% of his time battling tool problems, and 10% of the time working on actual content. Many overtime hours were required to meet the deadline.
At this point in time, the problems cannot be solved easily, but a dedicated analysis of the content can lead to a proper solution. It will be time consuming. If more thought had been given to how the approach would be managed and maintained, instead of unconditionally embracing the FrameMaker text inset functionality, the team would not find itself burdened with the problems it faces – with each release – today.
Hyperlink Hell
The RoboHelp project included mucho reference information concerning ActiveX control methods, properties, events, and enumerations used in the creation of custom controls for the particular product being documented. Nothing wrong with that; the problem I ran into was the fact that introductory topics existed for each section of content, with hyperlinks to each and every method, property, event, and enumeration in the introductory topics – over 300 in all.
While all those links may seem like a friendly thing to do for the user, the reality is that hyperlink creation and maintenance is very time consuming. As the ActiveX control library is expanded, new links must be added. The alphabetized table of hyperlinks needs to be reorganized. Over time, links can break, so additional testing is required for those hyperlinks.
Now, think about it? do users really need/will they even use all those hyperlinks? In an HTML Help file, the Contents pane sits at the ready, all topics listed and linked. And the Contents listing is maintained automatically by RoboHelp!
A much more efficient approach, equally useful for the user, would have been to introduce each section (methods, properties, events, and enumerations), then point the user to the Contents pane for a complete listing of each section.
In both of these cases, tools capability trumped an analysis of just what was needed by the user and how the solution would be managed in the future. Simpler, less tool-intensive solutions could have served users well, and helped ensure that developers would meet their deadlines.
Leave a Reply
You must be logged in to post a comment.
Connect With Us Online
Our award-winning Phoenix chapter provides industry support, education, community service, and networking opportunities for chapter members, students and local businesses.
Learn more