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

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:

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

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

Date

Description

21 September 2009

Second drafts complete; second internal review begins.

4 October 2009

Review of second draft complete; authors begin working review comments.

8 December 2009

Third drafts complete; third internal review begins. This review will include the OASIS DITA Adoption Committee and the OASIS Technical Advisory Board.

5 January 2009

Third review complete; author begin working review comments.

20 January 2009

Final draft ready to submit to OASIS for public review and official-approval process kick-off. This draft must include all substantive content; if we need to add substantive content after the public review begins, it will require us to restart the approval process Important: This date must not slip past 1 December 2009.

Decisions

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

Editorial guidelines

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:

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:

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:

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.

DITA_1.2_specifications:_Authoring_and_editorial_guidelines (last edited 2010-07-28 17:42:41 by sethpark)