TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
The way you described is the way Cisco does it and seems to be increasingly used in entries I see in STC competitons. Can't argue too much with an 800-lb. Gorilla! It's a compromise, but, IMHO, an acceptable one.
From: Nancy Allison <maker -at- verizon -dot- net>
Subject: Cross-reference style question
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Tuesday, December 1, 2009, 9:38 AM
I'm working in a long document that has internal TOCs at the beginning of each chapter.
They are presented in a simple list format, using the same x-ref formatting that is used in sentences. It's quick and easy but possibly not really stylistically acceptable. By that I mean, not stylistically acceptable TO ME. I'm wondering if my ideas of acceptability are stuck in, say, the 80s. It looks like this:
This chapter contains the following sections:
-- "Opening Your Toaster Box" on page 37
-- "Plugging in Your Toaster" on page 42
-- "Burning Your Toast" on page 67
Each bulleted item is a hyperlink and is formatted in blue ink, so that when people read the PDF online, they know they can click to go directly to that section. When the document is printed on a color printer, the text is blue, which may seem slightly odd, but the page number is provided so the reader can find the section.
Although it looks a bit kludgy to me, it is much easier to maintain than having two lists marked with conditional text:
--One has the blue hyperlink, no quotation marks, and no page numbers
--One has the quotation marks and page numbers, but no hyperlink
The two-formats-marked-with-conditional-text is what I have done in other documents, but I'm wondering if I am making work for myself and anyone else who has to maintain the docs.
Would you accept this alternate formatting? If not, what would you do instead?
Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at: http://www.doctohelp.com/
Help & Manual 5: The all-in-one help authoring tool. True single- sourcing --
generate 8 different formats and as many different versions as you need
from just one project. Fast and intuitive. http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as mkrupp128 -at- yahoo -dot- com -dot-
Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at: http://www.doctohelp.com/
Help & Manual 5: The all-in-one help authoring tool. True single- sourcing --
generate 8 different formats and as many different versions as you need
from just one project. Fast and intuitive. http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
