Let's be bold in how we think about this. And let's employ
technical communication best practices: Audience analysis, task
analysis, an audit of existing content, etc.
For example, I looked at the existing element reference
topics for the elements that will be in Lightweight DITA;
see https://www.oasis-open.org/committees/document.php?document_id=58913&wg_abbrev=dita-lightweight-dita
for a CHM and PDF of this content.
Audience
Purpose of content
Notes
DITA authors
Provide guidance about the semantics of
elements and when they should be used
Provide guidance about authoring best practices: Use
key-based addressing rather than direct addressing; use
relationship tables
Provide guidance about complicated syntax, such as
addressing or referencing images; encoding using entity
references; setting a key column on <simpletable>
<p>, <pre>, <xref>,
<simpletable>
<xref>
<xref>, <image>
DITA practitioners
Provides guidance about specialization
choices
<ph>
DITA information architects
Provide guidance about designing content
for reuse
Provide guidance about reuse best practices
<ph>
DITA implementors
Provides guidance about expected formatting
and rendering, processing
Provide guidance about complicated syntax, such as
addressing
Provides details about attribute-driven formatting, such
as @keycol
<pre>, <dl>, <li>,
<ul>, <simpletable>
<xref>
<simpletable>
I think we'd serve people well if we did the following (and
more):
Standardize the format of the short descriptions
Separate information about formatting and rendering
expectations to a specific section within element reference
topics; recompile that information (by reuse) into a separate
topic or appendix or document that can be referenced easily.
Move information about authoring best practices into
separate topics or documents.
Ensure that syntax is covered ONLY in one place, not
duplicated in the architectural topics and element reference
topics.
Simplify complicated topics that have grown over time, such
as <shortdesc>, <data>, and <map>. (I did
not mention those topics in the table above, because they are
so ... complex.)
Address issues that people trip over (What happens to titles
in maps? Titles in relationship table?) using a consistent,
easily understood pattern.
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 9/8/2016 1:55 PM, Robert D
Anderson wrote:
I wanted to follow up on the discussion from Tuesday,
specifically regarding the suggestion that (I'm pretty sure)
came from Chris Nitchie.
The suggestion there was about changing how we think about and
publish the spec. Rather than using a hard-to-define
separation of "Architectural spec" versus "Language spec",
much of our content could be organized much more logically
into Processing and Grammar.
As I said on the call, I really like that idea. Kris and I
found during 1.3 editing that it could be very difficult to
make a distinction between what was "Architecture" versus what
was "Language". That difficulty doesn't entirely go away with
Processing and Grammar, but I think those groupings go a long
way to helping us better organize the content. That said -
those two distinctions don't cover everything in the
specification. I expect that if we make that sort of
reorganization, we'll end up with several better focused
sections.
I can think of a few good candidates for other major sections
of a 2.0 spec, based on sub-sections of the current
architectural specification:
- Addressing
- Specialiazation and modularity
- Grammar file construction
Are there any suggestions for additional types of content that
exist in the spec (and should continue to exist)?
Alternatively, do any of the sections I've listed seem like
the wrong direction?
Regards,
Robert
D. Anderson
DITA-OT lead and Co-editor
DITA 1.3 specification,
Digital Services Group
E-mail:
Digital Services
Group
11501 BURNET
RD,, TX, 78758-3400, AUSTIN, USA
Kristen James Eberlein ---09/06/2016
09:57:56 AM---DITA 1.0: Separate architectural spec and
language reference DITA 1.1: " "
From: Kristen
James Eberlein <>
To: DITA
TC <>
Date: 09/06/2016
09:57 AM
Subject: [dita]
DITA 2.0: How might we reorganize (reformulate?) the spec
for DITA 2.0
Sent by: <>
DITA 1.0: Separate architectural spec and language reference
DITA 1.1: " "
DITA 1.2: Aggregated archSpec and LangRef
DITA 1.3: " " and three editions
What do we want to consider for DITA 2.0?
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS
TC that
generates this mail. Follow this link to all your TCs in
OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
