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: "Dr. Stanley Doherty" <stan@modularwriting.com>
- Date: Wed, 2 Sep 2015 21:04:39 -0400
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]