Understanding when to use “see” and “see-also” references in an index is essential for providing users with alternative access points to relevant information.

Using “See” References

You should use “see” references in an index when you want to direct users from one term or entry to another term that is more appropriate or commonly used. “See” references are used when there might be synonyms or alternate terms for a concept, and you want users to find the information under the preferred term. For example, if you have an entry for “Electronic Mail,” you might include a “see” reference that redirects users to “Email,” which is a more commonly used term.

Using “See-Also” References

“See-also” references should be employed when you want to guide users to related but not synonymous terms or concepts. These references provide additional information that users might find useful in conjunction with the current entry. For instance, in an index entry for “Database Management System,” you could include a “see-also” reference to “Relational Databases” to help users explore related topics that enhance their understanding.

Example:

Here’s an example in DITA XML format illustrating the use of “see” and “see-also” references in an index:

<index>
  <entry term="Electronic Mail" loc="email.html" />
  <entry term="Email" loc="email.html" see="Electronic Mail" />
  <entry term="Database Management System" loc="dbms.html" />
  <entry term="Relational Databases" loc="relational_db.html" see-also="Database Management System" />
</index>

In this example, “Email” is a “see” reference to “Electronic Mail,” indicating that users should refer to “Electronic Mail” for information on this topic. On the other hand, “Relational Databases” is a “see-also” reference to “Database Management System,” suggesting that users might find both topics relevant.