Hi, Laura, This is a terrific example -- it shows and describes the correct structure for the topic type, keeping it simple -- omitting the optional tags we would prefer that people not use (like <titlealts>, for example). I can see that parts of this can be used for the other topic types as well.
I'd suggest sticking to an 80-character line length for easy readability in text editors, if possible. Some questions: Under INDEX ENTRIES, would it make sense to provide the URL of the Derby Documentation page? Also, do we recommend a maximum nesting level for index entries (2?)? Do you want to include the <stepresult> and <result> tags? The <stepresult> one is used pretty often in our docs, the <result> one only occasionally. About not bolding the text inside a codeblock -- are you suggesting that we not provide any distinction between user input and system output? I think the doc conventions make that distinction in most places I have worked, and not making the distinction would be very confusing in Working With Derby, where the example intersperses input and output. Currently, bolding the user input in a codeblock works as long as the system output is not also tagged -- the bug in the toolkit involves the loss of white space *between* tags only, apparently. About the example codeblock in a substep -- is there a reason for all the spaces between CREATE TABLE and tablename? Was there supposed to be a line break and indent somewhere, or something like that? About choicetables -- I have made the unpleasant discovery that DITA allows you to put them in a step but not in a substep. In some cases I need them in substeps! So I use a simpletable in substeps -- but those look different from choicetables, especially in HTML. And actually, choicetables look kind of ugly in HTML: no vertical space top or bottom, and no vertical lines separating the two columns, which are very close together. I wonder if we need a toolkit fix. Failing that, maybe we should use simpletable everywhere just for consistency in appearance. :( Anyway, I've attached a slightly revised version with the 80-character lines and a few corrections of typos here and there. Thanks a million for doing this. I look forward to the other templates. And the other big job will be to come up with some guidelines for elements that can occur in text -- there are so many! Kim Laura Stewart wrote On 10/19/06 16:33,: > Here is a template file for a task topic. I would like to post this > on the Derby Documentation page. It can be used as a starting point > whenever someone has a new task that needs to be documented. > > Please look it over and comment on any additions or corrections that are > needed. >
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "../dtd/task.dtd"> <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <!--TOPIC TITLE: Clearly and succinctly identify the task. Begin the title with the gerund (the -ing form) of a specific verb, such as Subscribing, and maintain a verb-object structure. Avoid nonspecific verbs like "Using" or "Working with". For example: Encrypting databases with a new external encryption key The title for short description is the first paragraph in the topic and can be used as an abstract. Capitalize only the first word of a title, except for proper nouns within it.--> <task id="task_template" xml:lang="en-us"> <title>task_template</title> <!--SHORT DESCRIPTION: The short description is used for first paragraph in the topic and as an abstract. Short descriptions can be 1-3 sentences long.--> <shortdesc></shortdesc> <!--INDEX ENTRIES: Below is the tagging needed for index entries. To add an index entry, insert the <indexterm> tag inside the <keywords> tag. See the Derby Documentation page for guidelines on indexing a topic. --> <prolog><metadata> <keywords><indexterm>templates<indexterm>task</indexterm></indexterm></keywords> </metadata></prolog> <taskbody> <!--PREREQUISITES: If there are prerequisites that the user must complete BEFORE performing this task, add the prerequisites in the <prereq> section.--> <prereq></prereq> <!--CONTEXT: If there is additional introductory information for this task that the short description does not cover, type it in the <context> section. --> <context> <p>To [ do this task] ...</p> </context> <!--STEPS: The tags that you use for the steps depend on what you are asking the user to do. --> <steps> <step><cmd>Do this</cmd> <!--Use <choices> for a bulleted list of options on a single step.--> <choices> <choice>Using this method</choice> <choice>Or this method</choice> </choices> </step> <step><cmd>Then this</cmd> <!--Use <substeps> when there are distinct parts to a step. It is often helpful to have an example. Use the <stepxmp> tag and the <codeblock> tag for examples. Do NOT bold the text inside the codeblock.--> <substeps> <substep><cmd>which is done by doing this</cmd></substep> <substep><cmd>and then this.</cmd><stepxmp>For example: <codeblock>CREATE TABLE tablename (col1 INT NOT NULL, col2 DATE NOT NULL, col3 INT DEFAULT 0)</codeblock> ></stepxmp></substep> </substeps> </step> <step><cmd>And finally, this.</cmd> <!--Use a <choicetable> when there is more than one way to do something -- for example, when there are different commands/syntax for different operating systems (Windows/Linux).--> <choicetable> <chhead><choptionhd>Operating System</choptionhd><chdeschd>Step</chdeschd> </chhead> <chrow><choption>On Linux</choption><chdesc></chdesc></chrow> <chrow><choption>On Windows</choption><chdesc></chdesc></chrow> </choicetable> </step> </steps> <!--EXAMPLE: Use the <example> tag when you want to provide an example for the entire task. It is better to add examples within the steps (see substep b) instead of using this tag.--> <example></example> <!--POSTREQ: Use the <postreq> tag when you want to describe to the user what they can do after they complete this task. --> <postreq></postreq> </taskbody> </task>
