Derby web page on writing guidelines needs some fixes
-----------------------------------------------------
Key: DERBY-5182
URL: https://issues.apache.org/jira/browse/DERBY-5182
Project: Derby
Issue Type: Bug
Components: Documentation
Affects Versions: 10.7.1.1
Reporter: Kim Haase
Priority: Minor
The guidelines at http://db.apache.org/derby/manuals/guidelines.html need some
corrections and enhancements. One item is related to accessibility, but most
are not. I wish I could fix these myself, but I am not set up to edit the web
site.
The table in "Tagging examples - structural tags":
Tables: A title tag should be added to the table tagging example (as in the
example in the reference template):
<table>
<title>Title of table</title>
<tgroup ...
At the end of the tagging example I'd suggest adding the following text:
For accessibility, each table should be preceded by introductory text
describing what it does (for example, "The following table lists the
limitations on XML data types in Derby."). It is recommended not to use an
<xref> element to introduce a table. Make sure the table has no empty cells.
Index entries: The following sentences should be removed: "Index entries are
displayed at the end of the PDF output for each Derby manual. When there is an
Information Center, the index terms are added as metadata to help in searching
for content in the Information Center." The first sentence is not true, and I
believe the second has no meaning outside of IBM?
I had thought of adding an entry on using figures, but since any new figures
would not match the look of the existing ones, I hesitate to do so.
The table in "Tagging examples - textual tags":
Links to external sites: The sentence "To create links to other topics in the
Derby documentation, edit the ditamap for the source manual to specify a
related link to another Derby topic." should be changed:
To create a link to another topic within the same manual, use an <xref> tag as
in the following example:
<xref href="tgsrunningsysinfo.dita#tgsrunningsysinfo"></xref>
To refer to a topic in another Derby manual, do not link directly to it.
Instead, use tagging similar to the following:
For more information about scopes, precedence, and persistence, see "Properties
overview" in the <ph conref="../conrefs.dita#pub/citdevelop"></ph>.
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
