OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

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


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]