RE: Always use most specific markup?

[Cavicchio_Rob@emc.com]

Lasse Kliemann wrote:

> Should one always use the most specific markup available? For 
> example, sometimes it may be conceivable to use 'systemitem' 
> instead of 'filename', 'envar', or 'function'.


I don't think there's a yes-or-no answer to that question. It totally
depends on the information you are marking up, and how it might be used.

I do tend to lean toward being specific. Here are just a few of the ways
you can leverage more specific markup:

	- Identifying certain pieces of information to be handled
differently during the authoring process.
	- Formatting items differently in your output.
	- Creating index or search functionality that keys off specific
tags.

Also remember that it is easier to get more general than more specific,
so if you have any doubt, you might want to start specific.

All that said, there are some cases where the complexity of tagging
outweighs any benefit of distinguishing similar items. My group feels
that way about the <gui...> tags for example. We just use <guilabel> for
all GUI names, and forgo <guibutton>, <guimenu>, etc.

But every situation could be different. You should assess your own
information before making a final decision. 


*************************
Rob Cavicchio
Principal Technical Writer
EMC Captiva
EMC Corporation
10145 Pacific Heights Boulevard, 6th Floor
San Diego, CA 92121-4234

P: (858) 320-1208
F: (858) 320-1010
E: Cavicchio_Rob@emc.com

The opinions expressed here are my personal opinions. Content published
here is not read or approved in advance by EMC and does not necessarily
reflect the views and opinions of EMC.