Next in thread →
Next in month →
Re: [dita-lightweight-dita] Software Engineering Use Cases
"Element count" is a curious thing: the DITA 1.1 map of Stan's opus
has 11 start/end tags actually showing in the source view despite
the number available but not opted for, while the lightweight map
has 45 elements/ 90 start/end tags despite its smaller overall
element inventory. Not everyone who compares the two instances would
agree, on the face of it, that the latter is convincingly
lighterweight!
The marketing writer who is not using a $900 editor won't see either
inventory of tags available in the contextual pulldown of the two
systems; they will see only the one title field and an "insert link"
button in the simplified form interface. If the web tool designer is
going to have a say in which architecture he or she wants to
support, we'll have to really work on the full value proposition
(where hopefully the specialization patterns will make a compelling
difference, but it would be nice if the artifacts were still not
quite so pointy).
(All of which is why I'm frustrated with the tools community for
striving for feature parity (e.g,"support every tag and attribute in
the schema" or "every CMS-oriented DITA feature") while failing to
provide task-appropriate interfaces for whole classes of
writers/adopters who are not full-time technical writers and would
never need to use the full toolkit.)
The simpler-looking DITA 1.1 map instances won't work in a toolkit
that supports the lightweight DITA architecture exclusively, will
they? I suspect there is only such much that you can do to make the
1.1 instance fully compliant in the LwD schema.
At this point the link model from related links starts to look
pretty interesting because it already has the more concise linktext
data structure like the topicref/title you mentioned. Am I crazy for
casually wishing that now would be a good time to rationalize those
two models (and their attendant processing) into one?
--
Don
On 9/4/2015 2:42 PM, Michael Priestley
wrote:
- agreed that the
basic doctypes still
need the highlighting domain
- agreed that shortdesc should be
optional
- agreed that map should have an
id
- agreed that topicmeta should be
optional
in topicref
For the map title: would you
rather
add the title element back in? It will increase the element
count for map
by 1 (right now it's only 6, and I was looking to cut down
wherever I could).
I confess I don't understand your objections to using
topicmeta/navtitle
for the map title, other than the extra containment overhead -
its attachment
to the map as a whole, rather than a specific topicref, should
be clear
from the DOM.
We did talk about introducing a
generic
<title> element for topicref outside of topicmeta for DITA
1.3 so
we could leverage it in lightweight DITA - the downside would
have been
that all existing processors wouldn't recognize it. That said
I've been
kind of surprised by how few existing processors recognize
topicmeta/navtitle
as a legitimate alternative (to either map/title or @navtitle).
But adding
it as this stage would pretty thoroughly break backwards
compatibility
so I think we're stuck with the extra containment (which also
conveniently
groups any <data> elements you might need/specialize,
FWIW).
Michael Priestley, Senior Technical Staff Member (STSM)
Enterprise Content Technology Strategist
http://dita.xml.org/blog/michael-priestley
From:
"Don R. Day"
<>
To:
Date:
09/04/2015 10:32 AM
Subject:
Re:
[dita-lightweight-dita]
Software Engineering Use Cases
Sent by:
<>
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:
1. 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.
2. 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
http://dita.xml.org/blog/michael-priestley
From: "Dr.
Stanley Doherty" <>
To:
Date: 08/28/2015
05:22 PM
Subject: [dita-lightweight-dita]
Software
Engineering Use Cases
Sent by: <>
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
--
Don
R. Day
Founding Chair, OASIS
DITA Technical Committee
LinkedIn: donrday Twitter:
@donrday
About.me: Don
R.
Day Skype:
don.r.day
"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
--
Don R. Day
Founding Chair, OASIS
DITA Technical Committee
LinkedIn: donrday Twitter:
@donrday
About.me: Don R. Day Skype:
don.r.day
"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
Next in thread →
Next in month →