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.
Subject:Referring to HTML tags in documentation From:Susan Kocher <sukoch -at- NEWZLGN10 -dot- UNX -dot- SAS -dot- COM> Date:Thu, 5 Nov 1998 19:54:17 GMT
Hi all,
I'm currently editing a book that refers to tag and attribute names. I
some cases, tags or attributes are named within a paragraph; in other cases,
what we are looking at is example HTML source code, like in a screen dump.
The question arises, should we use uppercase in naming tags and attributes
Lower case? Should tag names have angle brackets around them when we refer to
them in paragraph text?
Here are some examples of different ways you could refer to the same things
Every html document must begin with <html> tag and end with an </html> tag.
Every HTML document must begin with an HTML tag and end with an /HTML tag.
Every HTML document must begin with an <HTML> tag and end with an </HTML>
tag.
[related question: "a" or "an" /HTML tag??!)
The href attribute points to a name attribute in another location.
The HREF attribute points to a NAME attribute in another location.
The HREF= attribute points to a NAME= attribute in another location.
(I think this last one is a relic of our own company's convention in
documenting
software option names that sometimes have = in them.)
HTML markup itself is not case sensitive, so as far as I can see, the only
things we need to consider are (in my order of importance):
1) User readability
2) Any consensus out there already in the world of html (or HTML!)
documentation
Here are my thoughts on the above issues.
User readability should be our primary concern, and obviously uppercase is
easier to pick out and identify as tag/attribute names. In the HTML course I
took through the STC, I was taught to get in the habit of always using
uppercase in my own markup so that I could more easily analyze it later.
(The same goes for indentation of HTML source code--which is another issue
we can talk about!) In reality, of course, many of us are too lazy to
bother hitting that shift key for every tag or attribute name when we are
writing our own HTML, but that's because we hope to never look at it again
once it's done, and we don't really care if anyone else looks at our source
But in our software documentation, we do have an audience to consider.
The angle brackets help, and although they are in most cases be giving
redundant information (i.e. "this is a tag"), I think they are visually
useful. Especially when you are talking about tags like <A> or <P>--it looks
confusing to talk about "the p tag," much less "the a tag" or even "the A
tag." I prefer "the <A> tag".
Consensus? I looked in several
well-thumbed HTML books in our library, and found some that used all
uppercase, but several that used a mixture (I guess they didn't have a good
tech editor!). Laura LeMay, author of best-selling books like "Learn HTML in
14 Days" is pretty careful about using uppercase for all tag and attribute
names, whether in paragraph text or in a screen dump of HTML source code. I
think it looks best, personally. Other authors mix and mash throughout their
books, or
do one thing in Chapter 1, another in Chapter 3 (perhaps different writers
involved, perhaps different time frames/moods?).
As for using angle brackets for tag names in paragraph text, again there is no
consensus.
As we say down here in Nawth Kal Lyna, what do y'all think?
Thanks!
Sue
(please reply to the list or else remove the "z" from my address above if you
want to reply privately)
