Hi, DITA TC members.
Here is a table that summarizes potential action items from our (lengthy) discussion of DITA complexity. Many thanks to Stan Doherty for the initial summary! Take a look, mull it over, and we’ll discuss the items and which ones to prioritize at a future DITA TC meeting.
Goal | Task | Primary owner | Methods/Tactics | Notes | Roadblocks |
More feature articles about DITA | Monitor use cases developed by DITA TC and use them as a foundation for feature articles | DITA Adoption TC | |||
Author and publicize feature articles | DITA Adoption TC | Need for OASIS style rules for non-normative work products | |||
Author and publicize a feature article about basic DITA features | DITA Adoption TC | Need for OASIS style rules for non-normative work products | |||
Make robust sample files available to users | Produce high-quality sample files and code snippets | DITA TC | · Require that new feature proposals (DITA 1.3 and later) include sample working files, if at all possible · Improve the quality of code snippets in the DITA specification. Ensure that they can be instantiated and processed as working sample files. · Consider developing a sample set of DITA files for each DITA release, similar to the S1000D bicycle sample | Preserve the critical distinction between sample DITA files, which are intended to promote learning, and test files which are intended to promote compliance. | |
Publish sample DITA files in conjunction with feature articles | DITA Adoption TC | Need for OASIS style rules for non-normative work products | |||
Develop an index of sample DITA files on dita.xml.org | DITA Adoption TC | ||||
Make DITA information easier for people to find | Explore possibilities for increasing the precision and usefulness of Google search results | DITA TC? | |||
Improve dita.xml.org | DITA Adoption TC | ||||
Make it easier to create subsets of the DITA specification | Ensure that the specification is designed in such a way that subsets can be built | DITA TC | This was done for DITA 1.2. The spec could be built in the following configurations: · Base only · Base + technical content · Everything Of course, we can improve on the design for future releases. | ||
Document and publicize how to produce subsets of the specification | DITA TC? DITA Adoption TC? | For DITA 1.2, Stan Doherty built a page on dita.xml.org: http://dita.xml.org/wiki/dita-12-specification-building-specification-subsets . However, this Wiki page only discusses building subsets for the following entities: · Introduction · Architectural specification · Language reference · Conformance statement · Non-normative information | Which TC should own produce a formal document giving people more information about producing subsets of the specification, using the new non-normative track? | Need for OASIS style rules for non-normative work products | |
Support and publicize a DTD/Schema shell generator | Officially support a DTD/Schema shell generator | DITA TC | · Work with Jarno Elvirta | We’ve tried to go down this road in the past. Did we encounter impossible obstacles? Might this be different with a new TC Administrator? | |
Document and publicize a DTD/Schema shell generator | DITA Adoption TC | Already underway – Marc Speyer has drafted an article about Jarno’s DTD/Schema shell generator | Need for OASIS style rules for non-normative work products | ||
Make more default document types available | DITA TC? DITA Adoption TC? | ||||
Make it easier for users to create a minimalist DITA implementation | Develop a starter set of DTDs and constraints | Ad hoc effort of DITA TC members | Michael and Don are interested in participating in this as a “skunkworks” activity | ||
Publicize the starter set of DTDs and constraints | DITA Adoption TC | Need for OASIS style rules for non-normative work products | |||
Develop and publicize a robust repository of well-known specialization | Develop a repository | Ad hoc effort of DITA TC members | JoAnn, Robert, and Michael have volunteered to think about this: · What is the appropriate location: dita.xml.org or SourceForge? · How to classify and rate the specializations? | ||
Publicize the repository | DITA Adoption TC | Need for OASIS style rules for non-normative work products | |||
Provide potential users with better information about “What DITA do I need to know in order to accomplish specific goals?” | Review the DITA maturity model and consider it as a framework for organizing and orienting the discussion | DITA Adoption TC | |||
Develop a brief reading guide to the DITA specification | DITA TC | · Ask “What’s the learning path at each stage of the maturity model?” · Correlate features to usage and demographics | |||
Publicize the reading guide to the DITA spec | DITA Adoption TC | Need for OASIS style rules for non-normative work products | |||
Address misperception that information typing is a hard requirements for using DITA | DITA Adoption TC | User should be aware that ignoring information typing reduces the scope of what can be accomplished in DITA | |||
Address misconceptions about DITA | |||||
Best regards,
Kris
Kristen James Eberlein l DITA Architect and Technical Specialist l SDL Structured Content Technologies Division l (t) + 1 (919) 682-2290 l keberlein@sdl.com
Please consider the environment before printing this e-mail
From: Stan Doherty [mailto:stan@modularwriting.com]
Sent: Wednesday, June 15, 2011 10:52 AM
To: dita@lists.oasis-open.org
Subject: [dita] Summary of Working Resolutions Regarding DITA Complexity
Hi all --
Here's my summary of resolutions from the past few TC meeting discussions. I have cross-posted them to the "Complexity" web page itself at http://wiki.oasis-open.org/dita/DITA_Perceptions.
Stan
WORKING RESOLUTIONS
====================================================
http://wiki.oasis-open.org/dita/DITA_Perceptions
Item-1 -- The DITA Adoption TC should recruit more people to get involved with writing articles about DITA. Contributors (ideally) need to be active members of the Adoption TC, although there are opportunities for collaboration. For example, perhaps a TC member can work up a set of working examples on a feature prior to handing that off to an Adoption TC person for doing a write-up.
Item-2 -- The DITA TC should for DITA 1.3 make it easier to create subsets of the DITA documentation. Robert commented that there is almost certainly room for better documentation subsetting with DITA 1.3. He would be involved with doing the implementation work, but needs other people to offer suggestions and insights on what to do.
Item-3 -- The DITA TC should make Jarno's DTD/Schema shell generator more widely available and officially supported.
Item-4 -- The DITA TC should create default document types that include fewer domains a la the base topic.
Item-5 -- The DITA TC should make specialization easier (new rules, tools, auditing aids). Fir DITA 1.3 - Michael Priestley summarized some thoughts that he has been having about building into DITA 1.3 a template-based interface against a subset of DITA features that would allow users to pick and choose what they would like to see included in a constraint. This completed template could be exported to multiple tool environments. A dedicated working group would be one approach to getting this done.
Item-6 -- The DITA TC should provide a repository of well-known specializations. JoAnn, Robert, and Michael will get together to figure out how to make the specialization repository work, whether it be an extension of dita.xml.org or a Sourceforge submission. Figuring out how to search them and classify/rate them would be important. Rating guidelines for authors and submitters will be needed.
Item-7 -- The DITA Adoption TC should develop a feature article addressing "what is the most basic set of DITA features" would be useful for people learning DITA.
Item-8 -- The DTA TC should review alternative "views" of the DITA architecture in order to determine if there is a better way to capture and present the architecture to existing and new users. For example, reviewing Rob Hanna's proposal about abstract classes or other notions of type hierarchies might serve as a starting point.
Item-9 -- The DITA TC should assist in providing new users with a "minimalist" implementation of DITA by developing a starter set of DTDs and constraints. Hand this off to DITA-Adoption-TC. Michael and Don are interested in participating as a skunkworks activity within the TC. Members of the TC and of the BusDocs SC are solicited to participate and perhaps own.
Item-10 -- The DITA Adoption TC should leverage the to-be-developed "starter set" of DTDs/constraints and promote awareness of this "minimalist"/"no frills" path toward learning DITA.
Item-11 -- The DITA Adoption TC should address the perception that information typing (especially through DITA topic types) is not a hard requirement for learning or using DITA. That said, new users should be aware that ignoring information typing reduces the scope of what can be done in DITA (topic.dtd, basic maps).
Item-12 -- The DITA Adoption TC should review the DITA maturity model (Priestley, Swope) as a framework for organizing and orienting the discussion about "what do I need to learn in DITA in order to achieve XXX or YYY or ZZZ goal?"
Item-13 -- The DITA TC should develop a brief "reading guide to the DITA spec" that correlates features to usage/demographics. What's the learning path at each stage of the maturity model? How to move to the next level? (Organizations and individuals sometimes get stuck.) Individual TC members are encouraged to contribute rough draft material to the Adoption TC. Stan, Darryl, Kris, and Don have volunteered to help.
Item-14 -- The DITA Adoption TC should add to the DITA XML site (http://dita.xml.org/resource-directory) an index of sample DITA files developed in support of the feature articles.
Item-15 -- The DITA TC should for DITA 1.3 develop and review sample code snippets in the spec from the perspective of making them more easy to instantiate and process as working samples.
Item-16 -- The DITA TC should add a requirement to the DITA 1.3 proposal development and review process about sample files. If feature advocates and champions can develop and make available working samples of proposed new features, that might go a long way toward making those new features testable and promotable. Generating feature-specific equivalents to the S1000D "bicycle" example would be great. Preserve the distinction between creating "sample files" to support learning and "test files" to address compliance.
Item-17 -- The DITA Adoption TC should monitor the new-feature use case examples developed in the DITA TC to use as a foundation for DITA 1.3 feature articles.
Item-18 -- The DITA-TC should explore opportunities for increasing the precision and/or usefulness of Google search results about DITA.
Item-19 -- The DITA Adoption TC should explore opportunities for increasing the precision and/or usefulness of Google search results about DITA.
--
Stan Doherty