I converted Stan's list into a map of Lightweight DITA topics using
the latest DTDs (which I see now do not have fig in them yet--Mark's
goal was to pare back to just topic and map for moving forward).
Some observations on the usefulness of the present DTDs:
- "Element b is not declared in p list of possible children" -
something in the content model list for p? The better markup is
to use section titles in those locations, but this was still a
surprise.
- "Element topic content does not follow the DTD, expecting
(title , shortdesc , body , topic*), got (title body )" - in
standard DITA only title is required.
- Map cannot take an id. That makes them non-interchangeble with
a minimal standard DITA map.
- Standard <title> child of map now must be
<topicmeta><navtitle>. This has two impacts:
- In a list of peer topicrefs, all resolved titles are of
equal weight, so the first of equals is not necessarily the
right one when the map is aggregated.
- For a simple renditions of a list of topics, you can't use
the map to declare a true title (I'm having a semantic quibble
with navtitle thrust into playing two roles). I miss the child
<title> of map as a container title.
- topicref requires topicmeta, which requires navtitle.
Sometimes you just want a list of links and you'd rather let the
system tell you what the titles are, so this requirement was
annoying when trying to generate the simplest possible map for
the set.
- The topicmeta repercussions don't stand out if you are using
LwD like you'd use regular DITA, but Web users trying to build
their own tools might look at the syntactic overhead with the
usual complaints about XML for direct Web use. Happily, LwD
topics will include and run just fine in a conventional legacy
DITA map, and that is what I ended up providing for Stan's
broken-out topics.
- And as I look at that last comment, I worry about whether any
architectural heritage for DITA 1.3 may be at play in making the
LwD more constrained rather than less. I'm not sure that this is
the case for the particular issues I mention here, but I'm not
sure it's not, either.
To see these online, go to http://readx.ml and log in as
guest/guest. This is a demo expeDITA project for another team, but
we can use a back door to see Stan's content. Once logged in, go
directly to http://readx.ml/plan/outlines/map/StanStuff and then
play with the selector in the header to see his LwD content in
various characterizations. The Normalized view will let you better
explore the actual bones of the topics--here you can see the DITA
1.3 imprint in the DITAArchVersion attribute, for example, which
leads to consideration of compliant processing, for example.
Hoping this is interesting. Next week I'll replicate this site and
Stan's content to its own "LwD workgroup" so that we can all log in
and play with the content directly.
--
Don
On 9/2/2015 8:04 PM, Michael Priestley
wrote:
Thanks Stan - this is
great stuff! I love
your vision for lightweight DITA as a bridge across silos
(especially 7
and 8, though they're all good).
Is there anything more you can
say about
specific content type or element support?
I see a few scenarios where
tables are
definitely required, and diagrams - are those covered well
enough by simpletable
and image, in conjunction with a fig element wrapper to provide
title/caption
if needed?
Do there need to be any
topic-level
specializations, or could this all be done with generic topic?
Just trying
to get a sense of what's needed beyond the base package of just
topic and
map.
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley
From:
"Dr. Stanley Doherty"
<stan@modularwriting.com>
To:
dita-lightweight-dita@lists.oasis-open.org
Date:
08/28/2015 05:22 PM
Subject:
[dita-lightweight-dita]
Software
Engineering Use Cases
Sent by:
<dita-lightweight-dita@lists.oasis-open.org>
Hi --
I am coming at these use cases from the perspective of my day
job -- doc
manager, writer, people manager.
#01: MKT, TRAINING, and PUBS Share Product Reference Data
------------------------------------------
CURRENT PRACTICE: Technical Marketing folks (MS Word) author
product data
sheets and configuration specs that rely on fairly detailed
tables of required
and optional components. Pubs (DITA) and Training (MS
PowerPoint) also
use that same information.
LW DITA: If MKT, TRAINING, and PUBS could separately reference
the same
tables in stand-alone MS Word docs, that would be big win. All
three groups
HATE maintaining these tables; figuring out how do that
painful work ONCE
would be great.
- Maps: DITA
- Metadata: DITA (in map topicrefs)
- Topics: MS Word
- Publishing pipeline: DITA-OT or equivalent
#02: MANUFACTURING/OPS, TRAINING, and PUBS Share Systems Data
------------------------------------------
CURRENT PRACTICE: Many SW organizations layer their SW on
commodity or
proprietary systems (desktops, smart phones, servers, etc.).
For those
organizations, the Manufacturing (MS Word), Training (MS
PowerPoint), and
Pubs (DITA) groups separately maintain a collection of topics
that document:
- system setup
- cabling
- parts diagrams
- installation
- FRU installation/removal
Ugly stuff. The cost of this duplication is particularly nasty
here because
the mechanical art integrated with many of these topics needs
to be created
and managed in multiple formats -- JPG, PNG, SVG, and PDF. If
little MS
Word files containing these diagrams and associated tables
could be shared
across groups, win-win.
LW DITA:
- Maps: DITA
- Metadata: DITA (in map topicrefs)
- Topics: MS Word
- Publishing pipeline: DITA-OT or equivalent
#03: SWENG, TESTENG, and PUBS Share Basic Concepts and
Procedures
------------------------------------------
CURRENT PRACTICE: Many of the architects and engineers I work
with are
actually respectable writers. With a pep talk, some writing
guidelines,
and a fifth of scotch they have drafted many wonderful
stand-alone documents
that contain strong conceptual writing and nice procedures.
Almost as important
as WHAT they produce, is WHEN they produce it -- many weeks
and days ahead
of my team. If you can build into YOUR Agile user stories OR
Scrum team
DODs (Definitions of Done) that SW Engineers and Test
Engineers draft some
basic write-ups like this, the Pubs writers can integrate
those stand-alone
docs into DITA maps before rewriting it in DITA. I have seen
pre-release
(Alpha or Beta) SW release go out to early adopters that had
little more
than a dozen of these Engineer-authored pieces wrappered up in
a pretty
DITA map and processing pipeline. SW companies do not need to
have Pubs-authored
content at every stage of the SW development process. If
Engineers can
jump start the content development before Pubs group an roll
onto the project,
everyone wins.
LW DITA:
- Maps: DITA
- Metadata: DITA (in map topicrefs)
- Topics: Any combination of Markdown, HTML5, or MS Word
- Publishing pipeline: DITA-OT or equivalent
#04: SWENG and PUBS ITERATE ON DIFFICULT MATERIAL
------------------------------------------
CURRENT PRACTICE: There are some topics that we know in
advance will require
many drafts/iterations to complete. The writing and
diagramming per se
is not difficult, but engaging multiple architects, managers,
writers,
and engineers to converge on a shared understanding and
description can
be time consuming. Ironically, these sorts of tricky technical
topics also
the ones that are most valuable to our customers:
- load balancing
- high availability
- failover protection
- scaling up, scaling out
- troubleshooting performance issues
- site planning
- capacity planning
A writer on my team recently put a new document on high
availability metrics
through 20+ iterations with various engineers. If he had been
able to chunk
parts of that into separately editable stand-alone documents
for engineers
to update directly, the process would have gone more smoothly
and more
quickly. If writers could make judgement calls about routing
highly iterative
domains into LW DITA and meat-and-potatoes domains into DITA
1.3, our collective
efficiency as a software development organization would
improve. Once the
frequency of iteration calmed down, the LW topics could be
rolled into
DITA 1.3 topics.
LW DITA:
- Maps: DITA
- Metadata: DITA (in map topicrefs)
- Topics: Any combination of Markdown, HTML5, or MS Word
- Publishing pipeline: DITA-OT or equivalent
#05: SWENG and PUBS Collaborating Via and Confluence
------------------------------------------
CURRENT PRACTICE: Wikis in general and Confluence in
particular play an
important role in the overall SW development process these
days. Many SW
Engineering groups put all their planning and specification
writing in
Confluence pages. If there were key documents that contained
content that
could be shared with Pubs, it would be possible to
export/import content
in and out of Confluence as MS Word or XHTML docs. Messy, but
something
worth exploring (perhaps formally with Atlassian) in the
context of LW
DITA.
LW DITA:
- Maps: DITA
- Metadata: DITA (in map topicrefs)
- Topics: XHTML(5) or MS Word (kinda)
- Publishing pipeline: DITA-OT or equivalent
#06: SWENG and PUBS Sharing API Documentation Content
------------------------------------------
CURRENT PRACTICE: As APIs (especially REST) play a more
prominent role
in product portfolios, SW Engineering groups are turning to
API management
and publishing frameworks such as apiary, WSO2, RAML, Swagger,
etc.. SW
Engineers develop API code in the frameworks. Tech writers
have been authoring
Markdown or API Blueprint files that contain supporting
conceptual material
and examples. Some frameworks (notably RAML) can link to
stand-alone Markdown
files when building their interactive API web portals. With LW
DITA, these
Markdown topics could as easily be linked into DITA maps and
support traditional
Developer Guide publications.
LW DITA:
- Maps: DITA
- Metadata: DITA (in map topicrefs)
- Topics: Markdown
- Publishing pipeline: DITA-OT or equivalent
#07: Collaboration Between DITA and NON-DITA Departments or
Companies
------------------------------------------
CURRENT PRACTICE: I have never worked in a company that was a
100% DITA
shop. Partners, subsidiaries, subcontractors, offshore sites,
and peer
writing departments have their own publishing tools and
pipelines. Some
have guns and aren't afraid to use them. I haven't figured it
all out,
but I suspect that LW DITA could well be the
integration/convergence point
for multiple organizations contributing MS Word, HTML5, wiki,
or Markdown
content. Claiming the high ground as it were. A demo down the
road in which
one LW DITA map referenced various topics in non-DITA formats
would be
compelling. Assuring peer documentation groups that they could
eventually
contribute content to a large publication without having to
abandon their
current authoring tools would reduce stress.
LW DITA:
- Maps: DITA
- Metadata: DITA (in map topicrefs)
- Topics: LW formats that could be customized as exports from
Flare (HTML5),
FrameMaker (XHTML), or MS Word.
- Publishing pipeline: DITA-OT or equivalent
#08: CCMS-Hosted Topics
------------------------------------------
CURRENT PRACTICE: SW companies adopt multiple, specialized CMS
solutions
(silos):
- Support (MindTouch or ZenDesk)
- Marketing (SharePoint, Salesforce, WordPress, Drupal)
- Engineering (Confluence)
- Pubs (CCMS)
These systems tend to have REST APIs capable of allowing one
organization
to extract and process content from another's repository. If
one of the
formats of the document objects stored in these repositories
were LW DITA,
one could imagine (after a few glasses of wine) a scenario
whereby:
a. REST API requests from a DITA CCMS could extract the LW
DITA objects
from multiple corporate repositories
b. DITA maps organized the topics
c. DITA processors pushed the organized content through
multiple channels
Again, claiming the high ground and making CIOs think twice
about betting
the farm on wikis.
LW DITA:
- Maps: DITA
- Metadata: DITA (in map topicrefs)
- Topics: Any combination of Markdown, HTML5, or MS Word
- Publishing pipeline: DITA-OT or equivalent
==================================================================================
Closing: LW DITA is very promising stuff. The breadth of use
cases for
it will grow exponentially as more content developers become
aware of its
capabilities. Best of luck. I need to step back to complete a
DITA migration
at my day job, but I'll be with you in spirit.
Stan Doherty
--
"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
--T.S. Eliot
|
This email has been checked for viruses by Avast antivirus software.
www.avast.com
|
|