dita-lightweight-dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Re: [dita-lightweight-dita] Software Engineering Use Cases
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: "Don R. Day" <donday@donrday.com>
- Date: Fri, 4 Sep 2015 15:42:37 -0400
- 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
mpriestl@ca.ibm.com
http://dita.xml.org/blog/michael-priestley
From:
"Don R. Day"
<donday@donrday.com>
To:
dita-lightweight-dita@lists.oasis-open.org
Date:
09/04/2015 10:32 AM
Subject:
Re: [dita-lightweight-dita]
Software Engineering Use Cases
Sent by:
<dita-lightweight-dita@lists.oasis-open.org>
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
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
--
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
|
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]