dita-adoption-help message

Subject: Authoring and Editorial Guidelines for the DITA 1.2 Specification

From: "Stan Doherty" <stan@modularwriting.com>
To: dita-adoption-help@lists.oasis-open.org
Date: Tue, 18 Jan 2011 12:45:46 -0500

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.

http://wiki.oasis-open.org/dita/DITA_1.2_specifications%3A_Authoring_and_editorial_guidelines

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

Enjoy!!!

Stan

Stan Doherty
Director, Technical Publications
Verivue Inc.
Westford MA
sdoherty@verivue.com

Follow-Ups:
- RE: [dita-adoption-help] Authoring and Editorial Guidelines for the DITA 1.2 Specification
  - From: "Tony Self" <tself@hyperwrite.com>