db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Laura Stewart" <scotsmat...@gmail.com>
Subject Docs: Explain the types of DITA topics used in Derby documentation
Date Tue, 17 Oct 2006 22:46:58 GMT
The Derby Documentation web page http://db.apache.org/derby/manuals/dita.html
mentions that there are several types of topics in Derby
documentation, but does not explain what they are or how to choose
which type to use when you create new topics.

I think that the web page should have a new page off of it called
"Guidelines" and section that includes the following info:

Choosing the correct topic type

There are three types of topics used in the Derby documentation:
concepts, reference, and tasks.

Concept topics are overview information that answer the question "What
is...?". They explain "why" something is important or behaves the way
it does. Concepts provide the background information users must
understand before they can complete the tasks successfully.

Reference topics provide detailed information about product
capabilities for quick reference and for completeness. Reference
information provides quick access to facts, but no explanation of
concepts or procedures. Examples of reference topics are the syntax
for commands, and SQL statements, class descriptions, detailed
examples, and troubleshooting information.

Task topics answer the question "How do I?".  Tasks typically include
step-by-step instructions. Task topics often list (or link to)
prerequisites that need to be completed before the user can perform
the task. Tasks also list (or link to) any restrictions on performing
the task.

Laura Stewart

View raw message