Tech Write Tips

February 14, 2006

Best Practices: Write a Dictionary

Filed under: Best Practice — AndyR @ 1:48 pm

dictionary1.gifIt has been said that a dictionary is a:

“malevolent literary device for cramping the growth of a language and making it hard and inelastic. This dictionary, however, is a most useful work.”

This is the crux of the matter. The dictionaries imposed on us can be seen as cramping style and limiting creativty. However, if we use and own our dictionaires, they become tools that frame and enable our highest works of communication. Ownership and use are key, and go hand in hand. This is the basis of today’s best pratice suggestion. Start your own dictionary, make it particular to your work, then get in the habit of using it. I have found the following features useful in our in-house dictionary.

  • Build on existing style manual. We use Microsoft Manual of Style for Technical Publications, it’s not perfect but it gives us a starting point.
  • In your dictionary document it is useful to be able to sort in a variety of ways. We find it particularly useful to order entries by their created date.
  • Ideally your dictionary should be searchable, we do this with some xsl filtering, but as long as your is electroinc is should be pretty straight forward to search.
  • Finally, ensure your dictionary is freely and easily accessible to those who need it.

You should record your dictionary in the medium that best suites your needs. We use an xml file which is then transformed for viewing. This enables it to be viewable in  avariety of formats and quickly ordered or searched as required.

XML File:
 <Date></Date> – Date the netry was added to enable you to highlight new entries.
 <Update></Update> – Updated date to enable you to highlight updates.
 <Category></Category> – Grouping of the type of entry, is it general grammar, procedural or formatting.
 <Item></Item> – Unique reference for the item, usually the word or phrase in question
 <rule></rule> – A description of how the item should be used.
 <Correct></Correct> – An example of how the item should be used in practice.
 <Incorrect></Incorrect> – An example of how the item should not be used in practice.

XSL File:
<xsl:for-each select=”//Entry”>
 <xsl:sort select=”Update” order=”descending”/>
 <B><xsl:value-of select=”Item”/></B> <xsl:value-of select=”Category”/>
 <P><xsl:value-of select=”rule”/></P>
  <xsl:for-each select=”Correct”>
   <LI>Correct: <xsl:value-of select=”../Correct”/> </LI>
  <xsl:for-each select=”Incorrect”>
   <LI>Correct: <xsl:value-of select=”../Incorrect”/> </LI>
 <P><xsl:value-of select=”Date”/> <xsl:value-of select=”Update”/></P>

Best Practices: Delicious Topic Name

Filed under: Best Practice,Information Types,Navigation — AndyR @ 1:06 pm

DeliciousTopic titles, you can’t live with them, you can’t live without them. But these little text strings sitting incongruously at the top of our topics have an untapped power to enable users greater access to the information contained within.It wasn’t until I was recently using that I saw how key topic titles are to accessing information in helps. If you haven’t come across it yet, “ is a social bookmarks manager. It allows you to easily add sites you like to your personal collection of links, to categorize those sites with keywords.” It has had a meteoric rise to fame the past year.

This popularity is due to the power of this categorisation. The keywords associated with each bookmark enable incredibly powerful and flexible searching. This is something we can learn from for our helps. When users are searching for topics they do a keyword search and are presented with a list of topic titles. We have the oportunity of making these titles much richer by considering them as a series of “tags” that categorise the topic content, similarly to the bookmark “tags” in employing a strict naming convention to your topic titles, you can signpost key information to your users. To achieve this, you need to do some work on the type of information that you are going to include in your help. For example, you may include topics about Dialogs, Procedures and Concepts. Here are you first three “tags”.

Next consider each of these categories of topics and consider the types of information provided in each. For example, your procedure topics may contain information about creating New records, Editing, Deleting and Copying existings record. Htere are you next subset of “tags”.

Once you have completed this for all the types of topics in your help you will have a list of tags from which to compile topic headings for each topic.

The results is a help with strictly named topics, always using the same keywords (or “tag”) to identify the information it contains.

Although this may seem trivial (and not a million miles from what we would naturally do anyway), the application from an absolutely strict set of titles means that the user always has the same textual clues when searching for information.

Additionally, this approach prepares us for distinct topic categorisation as required by DITA and MAML. We can also make use of these categories to style topics differently for each type of information, providing further visual clues about the topic.

Finally, this also enables us to use topic titles if we want to generate a set of see also topics using some scripting technology.


« Previous Page

Create a free website or blog at