W3C home > Mailing lists > Public > www-qa-wg@w3.org > July 2004

[SpecGL] C1: Define your terms, GP 1

From: Dominique HazaŽl-Massieux <dom@w3.org>
Date: Mon, 26 Jul 2004 16:14:28 +0200
To: www-qa-wg@w3.org
Message-Id: <1090851267.29618.164.camel@stratustier>
1st GP for section C1; it would come after the principles

----------------
Good Practice: define the terms in-line, and consolidate the definitions
in a glossary section

What does this mean?
Put the definition of any new term along with its first occurrence in
the text, but make sure that all the definitions are also available from
a central glossary section.

Why care?
Having the definition in-line makes it easier to read the whole
specification from top to bottom, while having a centralized section of
defined terms makes it handy to look up a term when looking at a
specific section, or for others to re-use your definitions.

Technique:
- if you use XMLspec to edit the specification, using <termdef> and
<term> to markup the in-line definitions makes it possible to get
automatically a glossary with <glist>
- if you use XHTML, extracting the glossary from the in-line definitions
can be done with XSLT (see e.g.
http://www.w3.org/2004/07/def-to-glossary.xsl )

-- 
Dominique HazaŽl-Massieux - http://www.w3.org/People/Dom/
W3C/ERCIM
mailto:dom@w3.org


Received on Monday, 26 July 2004 10:15:04 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:14:33 UTC