Uploaded image for project: 'Derby'
  1. Derby
  2. DERBY-5182

Derby web page on writing guidelines needs some fixes

    XMLWordPrintableJSON

    Details

    • Type: Bug
    • Status: Open
    • Priority: Minor
    • Resolution: Unresolved
    • Affects Version/s: 10.7.1.1
    • Fix Version/s: None
    • Component/s: Web Site
    • Urgency:
      Normal

      Description

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

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              chaase3 Camilla Haase
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated: