OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita-adoption-help message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Authoring and Editorial Guidelines for the DITA 1.2 Specification

Hi all --
I had an action item to circulate the guidelines that authors of the DITA 1.2 specification used. Kristen and Gershon pulled this all together and made it work.
A few supplementary things also appeared in emails . . .
1. Revision tagging: Develop a scheme BEFORE going out fro tech review.
    - Example @rev="1.2.1"
2. Overlapping content: Develop a process/framework within which overlapping
    content between sections and authors can be identified. Once it is identified,
    it can be managed.
3. Concepts: Identify and collect key concepts as you write. Providing the key
    concepts up front help readability and technical review processing.
4. Unordered list sentence syntax: Make a decision for the sake of consistency
    about each <li> being constructed (or not) as a complete sentence.
5. Noun-phrase hyphenation: Authors and editors hyphenated them, e.g.
    base-DITA document types.
6. Copyright information: Tag it as you go. Collect and review it formally
    toward the end of the project.
7. <Indexterm> placement: Decide to put them in the topic <body> or
     <prolog>, but not in both.
8. Element and attribute names in running text:
    - <element-name>
    - @attribute-name
Stan Doherty
Director, Technical Publications
Verivue Inc.
Westford MA

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]