Linking and Relationship Tables

1. Linking and Relationship Tables Silicon Valley DITA User's Group This presentation is based on the DITA best practices and guidelines developed at IBM.

2. What you'll learn about today • Link definitions • General guidelines for linking • Types of links in DITA • How to create and use a Relationship Table • Best practices for Relationship Tables • Resources

3. Link definitions • Inline links:cross-references in the body of a DITA topic, including links: • To information within a topic or division • To information on other Web pages • Citations:Refer to a specific piece of information that is not available directly through a live cross-reference or a live link to a Web address. • Related links: links to related concept, task, and reference topics after the body of the dita topic. Related links can be links to other topics or to external content (web sites, pdf, etc.).

4. General linking guidelines • Inline links and citations can be disruptive to the flow of information. Try to delete them because: • A topic is a discrete unit of information that is meaningful when it is displayed alone. • Links outward from within the body of a topic break the user's concentration and attention to the task. • Users are smart people! They can use Search and also can find things through a nav tree. • The key question to ask, regarding any cross-reference or citation, is: Do I really expect users to go look at this other information right now? (Most of the time, the answer is no.)

5. When should you use inline links? • Cross-references within a topic or division are OK for long topics or divisions with multiple sections. • Cross-references to tables or figures are OK.

6. How to handle citations • Use citations sparingly because they subtly suggest that users leave the current information. • Use these citations only when users are very likely to need the related information at that moment in time.

7. Types of links in DITA • Related links • Hierarchical links • Family links • Sequential links • Relationship tables

8. Related links • Related links appear at the bottom of a DITA topic under headings such as "Related concepts," "Related tasks," "Related reference," and "Related information." • Although related links are less disruptive to flow than inline links, make sure you use them appropriately. Users can be overwhelmed by too many links.

9. Related links (cont'd) • Use related links to include links to closely related concept, task, and reference topics. • Examples: • A topic might include instructions for a product command with many parameters, so it would need a related link to a reference topic for that command. • A task topic might need related links to other task topics. For example, a task topic about granting privileges might need to link to a task topic about revoking privileges.

10. Guidelines for related links • Be careful not to repeat related links in the body of the topic. • Provide enough context for your references so that the reader knows which related link to look for. • If you delete an inline link and create a related link, you might want to beef up the text that's left behind.

11. Hierarchical links • Hierarchical links are parent-child links that are displayed at the bottom of DITA topics. • Hierarchical links are generated automatically when you nest topics in your ditamap.

12. Hierarchical links (cont'd) (Parent topic) (Child topic)

13. Family links • Family links are sibling links that are displayed at the bottom of DITA topics. • Use family links to include explicit sibling links in addition to hierarchical links. • Use family links when a group of topics, usually parallel to each other, is directly connected and is best understood as a unit. • Use family links sparingly because they generate multiple links in each topic, which can distract from the topic itself.

14. Sequential links • Sequential links indicate which topic precedes the current topic and which topic comes next in a series of topics. • At the bottom of a DITA topic, the preceding topic is marked with a "previous" link, and the next topic is marked with a "next" link • Use sequential links: • When topics are best understood in a sequential order • To connect steps that are single topic

15. Sequential links (cont'd) • Example of sequential links:

16. Relationship tables • "Reltables" are DITA relationship tables that use columns and rows to define the relationships between topics. • Use related links to provide users with additional information that is related to the current topic. • Use reltables to implement related linking that is not covered by prerequisite, hierarchical, sequential, or family linking. • You can create your reltables at the top of your master ditamap or in a separate ditamap. • Tip: Map out your reltables on paper so that you can see the structure of your links before you begin coding the reltables.

17. Example Reltable #1 w/ header row

18. Output from example reltable #1

19. Example reltable #2 w/out header row

20. Output for reltable #2

21. Using a maplist • You can use a maplist to control your ditamaps and reltables for a transform:

22. Questions?

23. Resources • The DITA forum on developerWorks at: • http://www-128.ibm.com/developerworks/xml/library/x-dita4 • The DITA yahoo group community at: • dita-users@yahoogroups.com • The members of your Silicon Valley DITA User's Group