Archive for the ‘Technical Writing’ Category

22 March

CHM Text Searches – Lesson Learned

The current project I am working on involves working on the CHM (Microsoft Help Files) for Windows Embedded Standard 7. This was a project underway before I joined the team and it had even changed managers during that time, which always creates at least a bit of chaos.

We just dropped our CHM files to the product team for integration last week and then discovered we had not completely purged the contents of the project’s internal name and prior release same in favor of the final release name. This happened despite having myself and four other people all search the Help for the string. It even happened despite a tool that would automatically check for the strings you tell it to at build time.

After dealing with the aftermath and rebuild/redrop (my boss was out of town), I looked into why this had happened and discovered I had let my tester mindset go to sleep and had not really thought in depth about how the searches were being done and the potential holes in these approaches.

The stage is set by:

  • The tool was checking for the term in the files at build time.
  • The individual searches done ad-hoc were using the search functionality provided in the Help by Windows when reading the CHM file.

The following discoveries were made as we looked into where this failed:

  • The tool does not check the index. Several instances of terms entered into the tool were found in the index.
  • Not all “bad terms” were entered into the tool’s database.
  • The Search functionality in Help does not search the index and no one thought to look there because the index was generated from files thought to be clean.
  • The Search functionality in Help is a regex-base search. All ad hoc searches were done with the same string, but no one thought to look for substrings with use of a wildcard before, after, or both in relation to the “bad string.” This meant no instances where the “bad string” was a substring could be found, though quite a few existed.

It seems obvious now, of course, but it really does help to look at these occurrences and see what the root cause was so that it can be caught in the future. In this case, we took away the following actions for the next release:

  • All terms must be entered in the tool’s database.
  • The CHM must be decompiled and the HTML contents searched for the “bad terms”. This will catch substrings and index occurrences.
  • Ad hoc searching must be done with wildcards and regex to also look for string and substring occurences.

Lesson learned and I paid the price. Both in terms of this instance’s particular issues and in terms of forgetting to look for holes in the process/testing – even if it’s not my job.

16 July

A Rant About Documentation

As both an author and a consumer of technical documentation as well as having some background in instructional design, I have some strong opinions about the role of documentation for a product. Over a decade in testing has also had an effect on how I view that documentation.

The most basic documentation is the help file that ships with the product. In Microsoft products, this is called a .chm (“chum”) file. Yes, I’ve probably thought of my share of bad jokes about that slang, too. I find myself currently involved in cleaning up the previously written .chm file for a new product as well as authoring new content for it and there have been some challenges.

Out of these challenges have come the start of my own personal list of DOs and DON’Ts for technical documentation.

  • DO know your consumer and know HOW they use the product to do their jobs.
  • DON’T sacrifice your reference sections in favor of only user story or scenario-based content.
  • DO use a more conversational voice to make the documentation easier to consume.
  • DO review customer feedback for opportunities to update your documentation to cover problem areas when appropriate.
  • DO produce other documentation besides just the .chm help files.
  • DON’T use the excuse of having other documentation to short-change the help files.
  • DO edit for professional voice and errors.
  • DON’T over-edit and lose technical accuracy in favor of prettiness of language.
  • DO offer tips and make sure gotchas are included.
  • DO make content easily findable and clearly identifiable by the consumers.
  • DO have your content thoroughly reviewed by the product team.
  • DON’T let the process of creating documentation get in the way of doing the right thing for the customer.

My background in shipping products has given me some valuable insight and gives me a solid base on which to work with the product team. I understand what they are talking about and don’t need a lot of hand-holding. They know I take deadlines seriously and am honest with them about where I am on my deliverables.

But I think documentation teams also really need to be able to turn on a dime. Things can change rapidly and you have to be able to roll with those changes.

Processes are required, both within the documentation team and where the documentation team has to interact with the product development team, but you really have to watch for signs that the process may be causing more overhead and pain that it’s solving. When a five minute task takes three days, an email thread of ten or more emails plus several requests being filed…you may have a problem.

You have to keep your eyes on the prize. The prize is excellent documentation to assist your consumers – not how well processes were followed or how many you have. No one will judge your documentation by how many people worked on it, how many processes were followed, who did what tasks or what tools were used to produce it. All consumers care about is how well it meets their needs.