Why Analyzer is more useful than Find and Replace for large support knowledge bases and long documents

Posted on June 25, 2009

0


MadCap Analyzer is great for long documents because it takes away a bit of the guess work and editorial work required to index and author long documents more consistently. The Index Keyword Suggestions that it lists is based on keywords you’ve chosen to index. So if there are other occurrences of a word, it’ll be listed. Not sure if it falls into the category of a concordance, but it does come very close.

analyzer-pic

I love Find and Replace. Use it all the time when we author with MadCap Flare. Its great for proofing text in the authoring and review cycles. Its simple, fast and infinitely useful. However, there is a wall to how far Find and Replace can take you.

When Find and Replace is just not good enough

Finding to match. It doesn’t store matching results beyond two output windows. Yes, you can output results to two different results windows (Output Windows) in Flare/Blaze. Personally I don’t view my search results in more than one window.

Save and execute saved searches. You also can’t save custom searches in Find and Replace in a list so that you can fix the same things consistently every time. If you did, you could create a quality checklist – so you automatically search for language inconsistencies in usage of tricky technical words.

Topic heading relationships. Inconsistencies in relationship issues (of the topical nested heading kind) between body text and headings are not immediately obvious. Example: number of heading 3s nested under a topic.

Maintenance of long indexes. Products don’t need new completely new help systems developed everyday. Most likely you already have a mix of old, new projects, and stuff you’ve never written before in your portfolio. If you’re updating an existing index for major documentation maintenance releases, then you need to be a little more careful with all the possible words that you may have been indexed before – or the ones you did not.

Using Concept keywords consistently. Flare has a pleasant indexing workflow when you’re authoring new topics. But if you’re updating an index six months later into a project, Find and Replace may not cut it. The same goes for Concept keywords –the keywords authors use for See Also links in WebHelp, Silverlight, AIRHelp and HTML Help.

The mind, it forgets things.

Old made new – a tool for long documentation and knowledge base word analysis

MadCap Analyzer is heavy on a strong rules-driven, analysis and regular expression engine to help you find common writing patterns, topic relationships, calculate authoring metrics and fix possible issues in your projects – things a documentation manager, senior writer or an editor might need in a project estimate and prior to release. Since, its rules-driven (you can’t create new rules but you customize them to a certain degree), so you or anyone else can do the same checks consistently, every time.

I find that this is most useful when you can put all this power to work for you especially for long documentation projects. A specialized tool like this helps you to:

  1. Create more consistent indexes
    You can use  Analyzer’s Index Keyword Suggestions to help you find possible topic and index keywords based on a matched list of words that you may have indexed before. This is especially useful if you’re updating projects that already have a comprehensive index or are part of long running collaborative authoring project and maintenance effort.
  2. Shave time off quality checklist reviews
    If you have a simple documentation quality checklist criteria to meet before a project is released, MadCap Analyzer could well shave some time by automating parts of the proofing process. More time for you.
  3. Create more consistent See Also links
    Find concept keywords you’ve used before and apply them.
  4. Reuse snippets and variables
    You probably remember that you have a companyName and productName variable set up. But what about that snippet you created last year on Friday, 7pm, when you added snippets for copyrights, boiler plates, publication numbers at the last minute?

The mind renewed.

As a matter of related interest and curiosity, I checked up on the meaning of a concordance. I ended up with this definition, “A concordance is a comprehensive index of the words used in a text or a body of texts. Usually there are also citations of the passages in which the words occur.” which I got from here.

About these ads