[bt-spec] BTP Issue 27 : Draft 0.9 is opaque,difficult to read and to understand.

[BTP issues maintainer <peter.furniss@choreology.com>]

This issue has been added to the BTP issue list

BTP Issue 27 : Draft 0.9 is opaque, difficult to read and to understand.

Category: editorial
Submitter: Bill Cox, (for all BEA members)
Submitter's identification: issue F
Detail:
The exposition makes this document very difficult to understand.  It is not
adequate to say that talking someone through it helps them understand -- the
document should be accessible from the written form, which is what will be
standardized. It is NOT enough that the editor and a few others can
understand the Draft if the goal is a broadly adopted public specification.
The previous elimination of what was called "Primer" material damaged the
accessibility of BTP.
Proposed Remedy:
Restore material with the goal of accessibility, and do a careful review
including non-initiates to ensure that the revised draft is clear and
understandable, and that presumably non-normative material is consistent
with the normative.

---

To comment on this issue, please follow-up to this announcement on the bt-spec@lists.oasis-open.org (replying to this message should automatically send your message to that list).

The current draft, with line numbers is available in pdf format and word format.

To add a new issue, please email to Peter Furniss peter.furniss@choreology.com. It helps if you propose a category (technical, minor technical, editorial, minor editorial).