• DITA_1.2_specifications:_Authoring_and_editorial_guidelines

DITA 1.2 specification: Authoring and editorial issues

Use this page to discuss and document authorial and editorial issues that arise as we write the architectural specification for DITA 1.2. Add your name and date in a parenthetical comment so that we can track comments.

Audience and purpose for the architectural spec

• The intended audience of the architectural specification is not a typical author or end user; the intended audience is people designing tools that work with DITA. Such people need to understand how the core elements of the DITA architecture work together. While the architectural specification is not intended to provide step-by-step instructions, it needs to contain enough topics that describe the overall flow, so that tools vendors 1) will understand how people will use DITA, and 2) will be able to properly implement the standard as intended ("spirit not just letter of the law.")
• The architectural specification should describe the architecture and the following features that are central (and unique) to DITA:
  • Content referencing (conref)
  • keyref
  • Linking generated through relationship tables and the hierarchy of DITA maps
  • Specialization and generalization
• The architectural specification should *not* include procedural how-to information. Rather, it should provide clear declarative statements of the rules, in particular the DTD or other coding rules for integration, specialization, and constraint implementation. (How-to and design pattern or other "best practices" information, while necessary to support accurate implementation, should be published through the DITA Adoption TC.) For the specialization and integration section in particular, the design goal is to present all the relevant rules in a single place, to address the issue with the 1.1 spec where the technical details were spread throughout different sections.
• The architectural specification should be the primary home for material about processing and complex processing semantics. [This will require moving some keyref material from the language spec to the architectural spec.]
• The architectural specification builds on the material covered in the language specification; it only duplicates material where necessary to create a coherent narrative. Whenever possible, duplicate material should be single-sourced using conref or keyref.
• The overview for the architectural specification should contain information about any changes in audience, as well as pointers to where any information that has been removed is located, for example, material about minimalism and the origins of DITA that is slated to be moved into the documentation for the Technical Communication package.

Concepts

See Key concepts for discussion about concepts, specialization terminology, and alternate TOCs.

Contributors

The following people are authoring sections of the 1.2 architectural specification:

• JoAnn Hackos ("Introduction to DITA," "DITA topics")

• Kris Eberlein ("About the DITA specification," "DITA maps")
• Gershon Joseph ("Metadata elements," "Common attributes")
• Nancy Harrison ("DITA processing", select specialization topics)
• Nancy Harrison and Robert Anderson (Localization)
• Erik Hennum (select specialization topics)
• Eliot Kimber (select specialization topics)
• John Hunt ("Learning and Training" architecture and language reference)

UPDATED 14 July 2009: The following people are reviewing sections of the 1.2 architectural specification:

• "Common attributes," "DITA processing")
• Stan Doherty ("DITA topics," DITA maps," select "Processing" topics)
• Dick Hamilton (select "Processing" topics)
• Sowmya Kannan ("Metadata elements")
• Bruce Nevin ("Metadata elements")
• Seth Park (select "Processing" topics, select "Specializing topics")
• Zarella Rendon ("About the DITA specification," "Introduction to DITA")
• Dana Spradley (Specialization)
• Su-Laine Yeo ("About the DITA specification," select "Introduction to DITA" topics, select "Processing" topics, Localization)

See the Excel spreadsheet (dita_specs_master_topic_list.xls) located in theSubversion repository for more information. Be sure to lock the Excel file before making any changes to it; Using TortoiseSVN contains information about how to do so.

Deadlines

Decisions

12 May 2009: The architectural spec will be authored using DITA 1.2.

Editorial guidelines

• 3 June 2009: Use @rev="1.2" for new 1.2 topics and for updated topics. Don't change @rev setting (or if missing, set to "1.1") for basic editing fixes (e.g. typos).
• 3 June 2009: Remove or merge topics that contain only title and shortdesc so that all topics (as far as possible) contain content beyond the title and shortdesc.

  • [Eberlein, 9 June 2009] I disagree with this. I think there is a necessary place for container topics: topics which contain only title and shortdesc and serve to group children topics. What we need to avoid is unnecessary container topics.

• [WEK] 9 June 2009: Use "element type" when talking about element types, use "element" element talking about element instances.

• [GLJ] 22 June 2009: New topics and major rewrites to existing topics should separate out normative information from non-normative information. Non-normative information should be marked up as <note type="other" othertype="Non-normative" outputclass="non-normative">. The idea is to implement this for DITA 1.2 where time permits, but we will not rework the spec to universally separate non-normative information out from normative information until DITA 1.3.

• NEW [Eberlein, 2 July 2009]: Use @rev="1.2.1" for content changed in response to review #1 comments.

• [Yeo] July 20 2009: The 'Terminology' topic says that attribute names may be preceded by @ and that element names may be delimited with < and > . I suggest we do this very liberally as it generally makes things clearer.

• [Yeo] July 20 2009: In the body of the spec, avoid saying that things are "new". E.g. "With the new keyref attribute, you can...". Then we won't have to go and clean up the wording when these things are not new anymore.

Open questions

[Eberlein, 29 May 2009] Here is a page where authors can list questions that cross their minds as they work on the first drafts. We'll use this page as a starting point for our first authors' meeting, scheduled for 3 June 2009.

[Eberlein, 8 December 2009] Here is page where I am moving the following sort of material:

• Content from draft comments that should be preserved, but which we do not want reviewers to see during review #3
• Review comments which authors deferred to a future release

Language Reference

Record comments about the Language Reference on this page.

Reviews

We will be using two mechanisms for reviewers to provide feedback to authors about topics:

• Edited HTML files (use to correct typos or make other small fixes; be sure to use an obvious font color)
• Wiki pages (use for substantial comments or discussion)

Review #1: 16-30 June 2009

Link to CHM version: http://www.oasis-open.org/committees/download.php/32957/archspec.chm

Link to TOCjs version: http://www.oasis-open.org/committees/download.php/32968/archspec_tocjs.zip

Wiki pages for first review

Review #2: 21 September - 3 October

Link to CHM version: http://www.oasis-open.org/apps/org/workgroup/dita/download.php/34300/dita1.2-spec-complete_20September2009.chm

Link to HTML version: http://www.oasis-open.org/apps/org/workgroup/dita/download.php/34324/dita1.2-spec-complete_20September2009.zip

Wiki pages for second review

Review #3: 8 December 2009 - 4 January 2010

Link to CHM version: <add URL here>

Link to HTML version: <add URL here>

Wiki pages for third review

Subversion repository

Here is the URL for the Subversion Repository:http://tools.oasis-open.org/version-control/svn/dita/

For source control policies, see SourceControlPolicy

For Windows users, Kris Eberlein drafted a topic about Using TortoiseSVN. This subversion client sits on top of Windows Explorer and is easy to use; it also has decent online help. The topic contains information about performing the following tasks:

• Installing TortoiseSVN
• Checking out a working copy of the architectural specification
• Uploading modified files to the Subversion repository
• Locking the Excel spreadsheet

Eliot Kimber also posted an e-mail about using the Subclipse plug-in for Eclipse or <oXygen/> as a Subversion client: http://www.oasis-open.org/apps/org/workgroup/dita/email/archives/200904/msg00021.html

Tagging guidelines

(bnevin, 12 May 2009) For subsections, use <section>, within subtopics if necessary. Don't use <dl> for subsections.

(Eberlein, 18 May 2009) Don't have multiple topics in a file. Use <section> elements; move material into additional topics if warranted.

Workflow

Use one of the following values for the Status column in the Excel spreadsheet:

1. Null: No work has been done.

2. Writing: Author is reworking the files and uploading modified files to the SVN repository as changes are made.

3. Ready for review #1: File are ready for the first review.

4. Review #1 completed: The first review is completed.

5. Working review #1 comments: Author is in the process of incorporating reviewers comments. Author is responding to comments on the Wiki pages and adding disposition ("Completed," "In progress," "Open," or "Rejected")

6. Ready for review #2: Files are ready for the second review.

7. Review #2 completed: The second review is completed.

8. Working review #2 comments: Author is in the process of incorporating reviewers comments. Author is responding to comments on the Wiki pages and adding disposition ("Completed," "In progress," "Open," or "Rejected")

9. Ready for review #3: Files are ready for the third review, which includes members of the DITA Adoption Committee and the OASIS Technical Advisory Board.