[ http://issues.apache.org/jira/browse/DERBY-2001?page=comments#action_12446714 ] Kim Haase commented on DERBY-2001: ----------------------------------
The reference template looks very good. Like the others, it lays out the correct sequence of tags and the most common usage. I notice it suggests to use a <codeblock> for syntax rather than <syntaxdiagram>, which seems wise. The <syntaxdiagram> element seems way too complicated; the descriptions and examples of its subelements in the DITA spec are hard to understand; and with these subelements, it is hard to tell from the source what the output will look like. Using a more wysiwyg tag keeps it simple. I would suggest that in these templates we use line breaks in logical places, to encourage writers of new topics to make them as readable as possible. For example, for the <refsyn> element, the draft shows the entire element contents on one line, with the only line break being the one required in the <codeblock> (though I'm not sure this will be clear here): <refsyn><title>Syntax</title><codeblock>CREATE [ UNIQUE ] INDEX <varname>IndexName</varname> ON <varname>TableName</varname> (<varname>SimpleColumnName</varname> [ , <varname>SimpleColumnName</varname>] * )</codeblock></refsyn> It might make more sense to do something like this: <refsyn> <title>Syntax</title> <codeblock>CREATE [ UNIQUE ] INDEX <varname>IndexName</varname> ON <varname>TableName</varname> (<varname>SimpleColumnName</varname> [ , <varname>SimpleColumnName</varname>] * ) </codeblock> </refsyn> I expect you also meant the sections on paragraphs and tables to begin on a new line. I just noticed that in the SHORT DESCRIPTION section in each template, "for first" should be "for the first". > Add DITA templates for the 3 topic types into the trunk > ------------------------------------------------------- > > Key: DERBY-2001 > URL: http://issues.apache.org/jira/browse/DERBY-2001 > Project: Derby > Issue Type: Bug > Components: Documentation > Affects Versions: 10.2.1.6 > Reporter: Laura Stewart > Assigned To: Laura Stewart > Fix For: 10.2.1.8 > > Attachments: concept_template.dita, derby2001_1.diff, > derby2001_1.stat, reference_template.dita, task_template.dita > > > Create templates for each of the DITA topic types - concept, reference, task > Add these templates to the Derby trunk so that anyone can use them. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira
