Embed Size (px)
DESCRIPTION
Linking and Relationship Tables. Silicon Valley DITA User's Group. This presentation is based on the DITA best practices and guidelines developed at IBM. What you'll learn about today. Link definitions General guidelines for linking Types of links in DITA - PowerPoint PPT Presentation
Citation preview
Linking and Relationship Tables
This presentation is based on the DITA best
practices and guidelines developed at IBM.
Silicon Valley DITA User's Group
Link definitionsGeneral guidelines for linkingTypes of links in DITAHow to create and use a Relationship TableBest practices for Relationship TablesResources
What you'll learn about today
Link definitions
Inline links: cross-references in the body of a DITA topic, including links:
To information within a topic or divisionTo 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.).
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.)
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.
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.
Types of links in DITA
Related linksHierarchical linksFamily linksSequential links
Relationship tables
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.
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.
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.
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.
Hierarchical links (cont'd)
(Parent topic)
(Child topic)
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.
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 orderTo connect steps that are single topic
Sequential links (cont'd)
Example of sequential links:
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.
Example Reltable #1w/ header row
Output from example reltable #1
Example reltable #2w/out header row
Output for reltable #2
Using a maplist
You can use a maplist to control your ditamaps and reltables for a transform:
Questions?
The DITA forum on developerWorks at:ƒ http://www-128.ibm.com/developerworks/xml/library/x-dita4
The DITA yahoo group community at: ƒ [email protected]
The members of your Silicon Valley DITA User's Group
Resources
