Uploaded image for project: 'Technical Advisory Board'
  1. Technical Advisory Board
  2. TAB-1275

Inconsistent numbering for examples

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: New
    • Priority: Minor
    • Resolution: Unresolved
    • Affects Version/s: Darwin Information Typing Architecture (DITA) Version 1.3 CSPRD01
    • Fix Version/s: None
    • Component/s: Public reviews
    • Labels:
      None
    • Environment:

      Style

    • Proposal:
      Hide

      Provide all examples with meaningful titles and section numbering to facilitate referencing by secondary (training) materials and users.

      Show
      Provide all examples with meaningful titles and section numbering to facilitate referencing by secondary (training) materials and users.

      Description

      This is related to your inconsistent sectioning but slightly different.

      I really do appreciate the work the TC has done to supply meaningful examples and to distinguish them from the normative text. You have no idea what it is like to read a standard that mixes them together.

      However, sometimes you title and section number examples and sometimes not. For example, 3.11.1.7 <learningAssessment> has potential subsections:

      3.11.1.7.1 Content Models

      3.11.1.7.2 Inheritance

      3.11.1.7.3 Example (which I would expand to be Example: <learningAssessment> and to be consistent with other cases where examples have section titles)

      ... continue with subsections to include Attributes, etc.

      Thinking this would facilitate referencing of examples by secondary learning materials that cite the standard and sharing of examples between users.

      As an example where you have already anticipated my suggestion, see: 2.3.4.10.15 Example: Keys and collaboration.

      So what I am suggesting is only an extension of what you have done already, but just not in every case. It would make the text more consistent and more useful to readers (thinking sections titled Example are less useful than Example: (some text here).

      Don't worry about overloading the TOC. You can always choose to only display headings down to some chosen level of granularity for a main toc and then full granularity (if you choose) for a full toc.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              patrick Patrick Durusau
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated: