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