OASIS Darwin Information Typing Architecture (DITA) TC

Expand all | Collapse all

Re: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0

  • 1.  Re: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0

    Posted 09-19-2016 14:51
    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: robander@us.ibm.com 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 <kris@eberleinconsulting.com> To: DITA TC <dita@lists.oasis-open.org> 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@lists.oasis-open.org> 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  


  • 2.  Re: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0

    Posted 09-19-2016 14:53
      |   view attached
    +1  I entirely agree with this approach. We should exemplify DITA best practices in our approach to DITA 2.0 and the spec. —Scott From: < dita@lists.oasis-open.org > on behalf of Kristen James Eberlein < kris@eberleinconsulting.com > Date: Monday, September 19, 2016 at 8:50 AM To: DITA TC < dita@lists.oasis-open.org > Subject: Re: [dita] DITA 2.0: How might we reorganize (reformulate?) the spec for DITA 2.0 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: robander@us.ibm.com 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 <kris@eberleinconsulting.com> To: DITA TC <dita@lists.oasis-open.org> 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@lists.oasis-open.org> 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