DITA 1.2 Specification: Committee Draft (CD) 01

This page contains feedback from Mary McRae on the version of the DITA 1.2 spec that that TC approved on 25 May 2010. It also contains information about our progress in discussing and correcting these issues.

Use this section to locate versions of the CD 01 and key OASIS templates and guidelines.

CHM version: http://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id=37932
XHTML version:http://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id=37933
PDF version: http://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id=37938
DITA source: http://www.oasis-open.org/apps/org/workgroup/dita/document.php?document_id=37937
DTDs: http://www.oasis-open.org/apps/group_public/document.php?document_id=37239
XSDs: http://www.oasis-open.org/apps/group_public/document.php?document_id=37189
Namespace document: http://www.oasis-open.org/apps/org/workgroup/dita/download.php/38161/DITA1.2-namespace.html

If you have problems opening the CHM:

  1. Save the CHM file to your local system.
  2. Right-click the CHM file, and then click Properties.

  3. Click Unblock, and then click OK. The contents now are displayed when the file is opened.

See http://support.microsoft.com/kb/902225/ for more information.

OASIS XHTML Template: http://docs.oasis-open.org/templates/OASISSpecificationTemplateV4.1.html
OASIS Namespace Document Template: http://docs.oasis-open.org/templates/namespace.html
OASIS Specification Quality Checklist: http://docs.oasis-open.org/templates/QAChecklistV3.html

Also, here is the home page for OASIS Templates and Guidelines: http://docs.oasis-open.org/templates/

Feedback from Mary !McRae

The following sections contain feedback that Mary McRae provided about the draft of the DITA 1.2 spec that the TC approved on 25 May 2010.

Cover page

(./) = Work completed
>:> = Work in progress
/!\ = Work not yet started

Issue

Comment

Status

Person

Date

Revision #

Specification URIs title is missing.

(./)

Eberlein

27 May 2010

892

Under This Version, please move the zips to the end and remove the note at the end of the DITA version.

(./)

Eberlein

27 May 2010

892

Under Latest Version, a URI must be provided corresponding to each 'this version' URI.

(./)

Eberlein

27 May 2010

892

In the Notices, please add "DITA" in the last paragraph (along with "OASIS")

(./)

Eberlein

27 May 2010

893

XHTML

(./) = Work completed
>:> = Work in progress
/!\ = Work not yet started

Issue

Comment

Status

Person

Date

Revision #

Section 1 must include Terminology (including RFC 2119 language), Normative References,
and Non-Normative References. This includes at least a normative reference to RFC 2119,
and I'm guessing XML but maybe others as well.
You can quickly view the formatting and citation here:
http://docs.oasis-open.org/templates/OASISSpecificationTemplateV4.1.html

(1) Renamed first topic to "Introduction"
(2) Added a "Terminology" section to the first topic
(3) Added a definition list with entries for "Normative references" and "Non-normative references"
Note: The contents of the OASIS template are not suitable for stand-alone topics.

Added separate topics for "Terminology," "Normative references," and "Non-normative references."

(./)

Eberlein

27 May 2010
3 June 2010

898
903

Section 1.2 History should go in the Appendix Revision History

(./)

Eberlein

27 May 2010

897

Appendices must be labeled as such (and not as Section 5):
Appendix A Acknowledgements
Appendix B Change History
Appendix C Migrating ...
etc.

(./)

Anderson

8 June 2010

Page footer:
Please use DITA v1.2 CD01 instead of spec name as currently displayed

(./)

Eberlein

27 May 2010

894

Section/subsection numbers are missing

(./)

Anderson, Eberlein

7 June 2010

'Parent' pages contain duplicated text

Added visual emphasis, plus topic explaing formatting conventions

(./)

Anderson, Eberlein, Priestley

7 June 2010

Navigation Links: Should also include 'previous' and 'next' rather than just 'parent topic' and 'previous topic'. For instance, if I'm at 2.1.1.1 I need to be able to get to 2.1.1.2 and should not have to go back to 2.1.1. 'next' should get me from beginning to end.

(./)

Anderson, Eberlein

7 June 2010

CHM

(./) = Work completed
>:> = Work in progress
/!\ = Work not yet started

Issue

Comment

Status

Person

Date

Revision #

The help pages don't display: (and there's no block/unblock in the properties window)

E-mailing back and forth with Mary; no work required.
Chris Goolsby confirmed that the CHM can be opened on Windows 7.
Modified readme to clarify that CHM files cannot be opened from a networked drive

(./)

Eberlein

27 May 2010

9000

PDF

(./) = Work completed
>:> = Work in progress
/!\ = Work not yet started

Issue

Comment

Status

Person

Date

Revision #

Cover page: hypertext links for specification URIs don't look like links (they are, but they should be blue/underlined)

(./)

Eberlein

27 May 2010

895

Running footer:
no rule
left side:
spec ID (DITA v1.2 CD01)
copyright
right side:
approval date (dd month yyyy)
Page # of #

(./)

seth park

on or before 07 June 2010

na

Notices and TOC starts a new page (same formatting as level 1 head)

(./)

Eberlein

27 May 2010

896

Running header:
no running header

(./)

seth park

on or before 07 June 2010

na

Text in all sections (1 - # and Appendices A - z):
should be flush left and not indented under section/subsection title

(./)

seth park

on or before 07 June 2010

na

Note much of the text in the tables is illegible or overset

XEP issue; use AH

(./)

seth park

on or before 07 June 2010

na

Level 1 (Section) heads:
There should be a rule at the top of the page (OASIS color)
18pt bold Arial #66616D

(./)

seth park

on or before 07 June 2010

na

Level 2 heads (#.#):
no rule
14pt bold Arial #66616D

(./)

seth park

on or before 07 June 2010

na

Level 3 heads (#.#.#):
13pt bold Arial #66616D

(./)

seth park

on or before 07 June 2010

na

Level 4 heads (#.#.#.#):
12pt bold Arial #66616D

(./)

seth park

on or before 07 June 2010

na

Level 5 heads (#.#.#.#.#):
12pt bold Arial #66616D

(./)

seth park

on or before 07 June 2010

na

Level 6 heads (#.#.#.#.#.#):
11pt bold Arial #66616D

(./)

seth park

on or before 07 June 2010

na

Level 7 heads (#.#.#.#.#.#.#):
11pt bold Arial #66616D

(./)

seth park

on or before 07 June 2010

na

Level 8 heads (#.#.#.#.#.#.#.#):
11pt italic Arial #66616D

(./)

seth park

on or before 07 June 2010

na

Level 9 heads (#.#.#.#.#.#.#.#.#):
11pt roman Arial #66616D

(./)

seth park

on or before 07 June 2010

na

DITA source

(./) = Work completed
>:> = Work in progress
/!\ = Work not yet started

Issue

Comment

Status

Person

Date

Revision #

Include a readme.txt in the zip to let people know where to start.

(./)

Eberlein

27 May 2010

892

Namespace document

(./) = Work completed
>:> = Work in progress
/!\ = Work not yet started

Issue

Comment

Status

Person

Date

Revision #

And I need a namespace document.

Added DITA1.2-namespace.html to SVN
Needs to be completed

>:>

Eberlein/Kimber

27 May 2010

899

CD01 (last edited 2010-06-08 16:26:15 by sethpark)