db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kim Haase <Camilla.Ha...@Sun.COM>
Subject Re: Docs: Explain the types of DITA topics used in Derby documentation
Date Wed, 18 Oct 2006 14:55:55 GMT
This is a very helpful introduction! Thanks, Laura.

There could be a link to this new page from "DITA File Names," since
that section is where the topic types are first mentioned.

It might also be helpful to include a link directly to the DITA language
specification and architectural specification; they are reachable from
www.dita.org, but you have to hunt a bit for them.

http://docs.oasis-open.org/dita/v1.0/langspec/ditaref-type.toc.html
http://docs.oasis-open.org/dita/v1.0/archspec/ditaspec.toc.html

Kim

Laura Stewart wrote On 10/17/06 18:46,:
> 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.

Maybe these should all be singular ("concept, reference, and task")?

> 
> 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.
> 


Mime
View raw message