DITA Whitepaper and Blog Planning

General Comments

The TC will be migrating this information to our Jira Tracker on the OASIS site. Please check the Tracker for new planning activities.

  1. Related areas: Many of these topics address common functional areas in DITA (e.g. keys, conditions) or common migration/implementation tasks (L10N, conversion). To capture potential synergy between things that we research and write, we've started grouping the issues whenever possible.

  2. Writing and leadership: As volunteers, we cannot expect to be able to handle this writing workload. In many cases, functioning as recruiters (for other authors), interviewers, social media facilitators, or editors will be more productive and reinforce connections with DITA users.

  3. Interviews: There are so many articulate DITA users out there now with invaluable insights and experiences with these topics. If we can identify DITA users who are willing to be interviewed by ATC members as part of the content development process, we can capitalize on the notion of DITA being a community-responsive standard. Conferences, user groups, listening sessions, LinkedIn groups, Twitter, and the Yahoo list are all venues to solicit contributors.

  4. OASIS membership and contributions: OASIS assumes that any publication approved by a TC has been authored by one or more of its members. Relative to a strategy that encourages contribution and participation by non-OASIS members, we'll have to figure something out.

  5. Listening session input: Many potential topics have been surfacing in the listening sessions to date.

  6. Survey/polling questions: Developing some best practices on our end for scripting questions for the community would be good. This would help to ground the readers (and potential contributors) into what we believe we want.


Legend

Updated item

Item in progress

A. Q1/2017 Work in Progress

Schedule

Area

ATC Members

Description

Q2/2018

Keys

Keith Schengili-Roberts, Bob Thomas

DITAADOPT-10: As a DITA information architect, I want to understand how to design manageable key definition maps.

Q2/2018

Keys

Leigh White

DITAADOPT-13: As a DITA information architect, I want to understand how to use conditional processing to manage multiple keymaps.

Q2/2018

Migration

Stan Doherty

DITAADOPT-12: As an MS Word user migrating to DITA, I want to understand where I should expect my MS Word skills to be applicable to DITA and where my MS Word skills are impediments.

B. Items accepted as candidates after review by the Adoption TC

Schedule

Area

ATC Members

Description

TBD

Keys

Keith Schengili-Roberts, Bob Thomas, Chris Goolsby

DITAADOPT-14: As a DITA information architect, I want to learn how to convert URI (hard-wired) references to key-based references outside a CCMS.
* Astoria has some technology to do this INSIDE their CCMS.
* Rudolfo Ryan may have some tooling here that has helped them with conref/keyref conversions for L10N.
* Perhaps the first step might be documenting best practices for how to do the conref-to-keyref conversion manually.
* It would be good to provide instruction/support for BOTH individual users doing a manual upgrade/conversion and vendors/CMSs doing an automated upgrade/conversion
* Possible TC issue: shouldn't the spec provide tooling/meta-scripts for these sorts of upgrade issues??

TBD

Conditions, keys

-

DITAADOPT-11: As a DITA information architect, I want to understand how the logic of content inclusion (keyrefs, conrefs, libraries) and the logic of content exclusion (conditional filtering) complement one another. How do I make the most effective use of each?

TBD

Conditions

TBD

DITAADOPT-15: As a DITA information architect, I want to learn about best practices for implementing conditional attribute values so they are maintainable across multiple releases.
* For DITA architects/users to understand some of the best practices for managing condition (and related DITAVALs), we may need to frame for them the benefits of some of the DITA 1.2 and 1.3 features designed to help (e.g. subjectScheme maps notably).
* Similarly, soliciting feedback and input from companies who have been managing conditions for a long time would offer reads some insight into the lifecycle of this information (creation, maintenance, retirement).

TBD

SVN/GIT, conditions

Scott Hudson

DITAADOPT-16: As a DITA information architect, I want to understand how the intrinsic branching and merging capabilities in source code control systems like GIT or SVN complement the conditional filtering capabilities in DITA. Under what circumstances (optimally) should I rely on branching to manage variance in my deliverables? Under what circumstances should I rely on DITA conditional filtering to manage variance in my deliverables?
* DITA Europe attendees have been visibly engaged with these sorts of issues. Perhaps recruiting some experts and interested parties there might jump-start this issue.

TBD

Metadata

Keith Schengili-Roberts

DITAADOPT-17: As a DITA Architect, I want to learn more about DITA metadata and SEO.

TBD

Metadata, bookmaps

-

DITAADOPT-18: As a DITA information architect, I want to understand how to design and manage the DITA metadata associated with DITA bookmaps.
* Eliot's DITA4Publishers and Leigh White's book on PDF customization get into this in some detail.

TBD

L10N

JoAnn Hackos, Keith Schengili-Roberts, +Rudolpho

DITAADOPT-19: As a DITA information architect, I want to understand how downstream translation memory tools handle the segmentation of content in XML. Is there anything that I can do in my DITA sources to optimize the frequency of matching segments?
* JoAnn and Keith plan to partner up on this one. Some focus on segmentation, some focus on how segmentation affects cost.

TBD

Migration

Stan Doherty

DITAADOPT-20: As an Adobe FrameMaker (unstructured) user migrating to DITA, I want to understand where I should expect my FrameMaker skills to be applicable to DITA and where they are impediments.

TBD

Migration

Bob Thomas, Scott Hudson

DITAADOPT-21: As an OASIS DocBook user migrating to DITA, I want to understand where I should expect my DocBook skills to be applicable to DITA and where they are impediments.
* The DocBook migration may have a different center of gravity than the other "lightweight" tool/format migration types.

TBD

Migration

Stan Doherty

DITAADOPT-22: As a MadCap Flare user migrating to DITA, I want to understand where I should expect my Flare skills to be applicable to DITA and where they are impediments.

TBD

XSLT

Leigh White

DITAADOPT-23: As a DITA information architect, I want to get an overview of how XSLT works.

TBD

UXD/Personnas

JoAnn Hackos, Keith Schengili-Roberts

As a DITA information architect, I want to understand how I might leverage Marketing or UXD personas when I design conditional processing (personalization) by audience.
* General information about personnas
* DITA-specific information about using subjectScheme maps to filter by personna facets
* See JoAnn's book User Task Analysis
* Keith has lots of background writing and research as well.

TBD

Agile

-

As a DITA information architect, I want to learn some practical techniques for referencing JIRA or Rally Agile assets from within my DITA sources. ex: <data>, @rev - Eliot
* Stan to do some research about integrating Agile metadata with the Release Management domain.

Q1/2017

Migration

Stan, Jane

As a documentation manager, I want to develop a DITA migration proposal (in DITA) that reflects the collective wisdom and experience of the DITA community.
NOTES:
* Include a setup topic instructing readers how to set up DITA-OT to build the boilerplate proposal.
* Include a section about the challenges facing writers in a migration -- training, workflow disruption, role changes.
* Incorporate lots of information about best=practice planning -- scheduling, training, conversion, etc..


C. Items put on hold after review by the Adoption TC

Area

ATC Members

Description

Small teams

-

As a DITA beginner, I'd like to know more about the DITA for Small Teams project and how it might provide my company with low-cost, open-source infrastructure.
* Eliot may well be covering this as part of his project. Beyond pointing to his project, not sure how much value we might add.

Collaboration

-

As a toolsmith, I want to know my options exchanging DITA content with existing lightweight markups, e.g. MS Word, Confluence wiki, Markdown, HTML5, FrameMaker, and MadCap Flare.
The sentiment if teh group was to give this some more time. Track the progress of LW DITA and re-evaluate where we might have gaps.


D. Items to consult with DITA TC

Area

ATC Members

Description

TBD

-

As a DITA information architect, I want to get an overview of how I can use XQuery to analyze my DITA sources.


E. Items to develop as dita.xml.org postings (rather than whitepapers)

Schedule

Area

ATC Members

Description

TBD

TBD

David Lance (?)

As a DITA information architect, I want to understand how to integrate videos with my DITA sources.

TBD

TBD

-

As a technology manager, I want to understand best practices for developing an RFP to DITA technology vendors.
* Lots of available literature here.
* VASONT article
* Existing dita.xml.org article is available.
* RIM (Research in Motion) had one as well.

TBD

TBD

-

As a DITA information architect, I want to understand how to model or respond to DoD requirements in DITA
* Need someone with specific requirements or experience to step forward.

TBD

TBD

-

As a writer or manager considering a DITA migration, I want to best practices for conducting a DITA pilot focused on assessing conversion costs.
* Stilo and DCR have some strong material that can be referenced and described.

TBD

TBD

-

As a writer or manager considering a DITA migration, I want to best practices for conducting a DITA pilot focused on assessing content models.
* Guessing here that people are looking for advice or guidance in develop in a content model

TBD

TBD

-

As a writer or manager considering a DITA migration, I want to best practices for conducting a DITA pilot focused on assessing output transformations.

TBD

TBD

(JoAnn)

As a communications professional interested in learning about the role of XML Information Architect, I want a list of available resources to support my learning.
NOTES:
* Incorporate information about relevant books such as Louis Rosenfeld's Information Architecture for the WWW and JoAnn's book Content Management for Dynamic Web Delivery
* Incorporate job description information
* Differentiate the web-oriented IA role from the XML IA role.
* Incorporate information about available training programs.

TBD

TBD

Don
Stan
Chris P?

As an information architect or toolsmith, I want to know my options for generating HTML5 content from DITA sources to integrate with HTML5 product interfaces.
* Stan: As software companies migrate the product GUI interfaces to HTML5/Bootstrap, there are requirements and opportunities to integrate DITA-generated Help content as viewports or panes in that product interface.
* Don: Targeting a particular HTML5 pane with DITA-generated HTML5 article content can be tricky. The DITA transformation pipeline may need to be tuned/customized.
* Don: Chris Despopoulos (TurboNomic, VMTurbo) has published work on this sort of integration. Slides available.
* Don willing help out here.

TBD

Style Guide

-

As an information architect, I would like to develop a DITA style guide for my organization based on best-practice guidelines developed by the DITA community in general.
* Review the Github Dynamic Information Model (https://github.com/oxygenxml/dim) as a starting place.
* Review Radu Coravu's posting on GitHub about a "model" domain of DITA sources that reflect best practices. See (https://github.com/oxygenxml/dita-project-best-practices).<<BR>> * Review Tony Self's DITA Style Guide at (https://github.com/hyperwrite/DITAStyleGuide).<<BR>> * Kris noted that this might be an opportunity to poll the DITA community to determine how many companies have developed their own style guides for element usage and/or general usage.
It was the sentiment of the group that we focus on publicizing available resources for teams to build their own style guide rather than build a source repo per se. Doing this as a blog is the way to do.


F. Items to be reviewed by the Adoption TC

Area

ATC Members

Description

TBD

-

Description

Brainstorm (last edited 2018-01-15 14:55:27 by StanDoherty)