s doherty stc-new_england_interchange-2014_03
DESCRIPTION
STC New England Interchange 2014 Conference PresentationTRANSCRIPT
![Page 1: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/1.jpg)
1© 2014 The MathWorks, Inc.
Best Practices in Modular Writing: Parallel Modeling in Word and DITA
Stanley Doherty, Ph.D.OASIS DITA Technical Committee Manager, Information [email protected] MathWorks Inc.March 30, 2014 [email protected]
![Page 2: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/2.jpg)
2
Arguments
A. Most best practices for modular writing can be implemented in anypublishing framework.
1. Segment your information2. Encapsulate each segment3. Type (classify) your information4. Organize the segments into maps 5. Curate and organize the shared content6. Conditionalize the processing pipeline7. Manage the content
B. If you focus on best practices, you can implement complementary, parallel modular documentation sets in very different authoring frameworks:- MS Word- OASIS DITA (Darwin Information Typing Architecture)
![Page 3: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/3.jpg)
3
Information Architectures (Purist)
UNSTRUCTURED STRUCTURED (XML)
LINEAR
MODUL AR
DocBook 4.xS1000D
DocBook 5.xDITA
MadCap Flare
MS WordOpen Office
FrameMaker (*.fm)
Wikis ?Web Pages?
Blogs?
![Page 4: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/4.jpg)
4
Information Architectures (Practical)
UNSTRUCTURED STRUCTURED (XML)
LINEAR
MODUL AR
DocBook 4.xS1000D
DocBook 5.xDITA
MadCap Flare
MS WordOpen Office
FrameMaker (*.fm)
Wikis ?Web Pages?
Blogs?
MODULAR WRITING (UNOPTIMIZED)
![Page 5: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/5.jpg)
5
Information Architectures (Practical)
UNSTRUCTURED STRUCTURED (XML)
LINEAR
MODUL AR
DocBook 4.xS1000D
DocBook 5.xDITA
MadCap Flare
MS WordOpen Office
FrameMaker (*.fm)
Wikis ?Web Pages?
Blogs?
MODULAR WRITING (UNOPTIMIZED)
![Page 6: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/6.jpg)
6
Information Architectures (Practical)
UNSTRUCTURED STRUCTURED (XML)
LINEAR
MODUL AR
DocBook 4.xS1000D
DocBook 5.xDITA
MadCap Flare
MS WordOpen Office
FrameMaker (*.fm)
Wikis ?Web Pages?
Blogs?
MODULAR WRITING (UNOPTIMIZED)
![Page 7: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/7.jpg)
7
Demo Environment
CONTENT Sun ISV Integrations Sun ISV Integrations
FILESYSTEM WINDOWS/MAC WINDOWS/MAC
SOURCE FORMAT .docx .dita(well-formed XML) (validated XML)
EDITOR MS Word SycroSoft Oxygen 15.2
PROCESSORS MS Word DITA Open Toolkit
OUTPUTS PDF, HTML PDF, HTML, ePubKindle, HTML5
CONTENT MGT - - - - easyDITA
UNOPTIMIZED OPTIMIZED
![Page 8: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/8.jpg)
8
#1 - Segment your informationMS Word DITA
![Page 9: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/9.jpg)
9
#2 - Encapsulate each segmentMS Word DITA
ibmnetcool_intro_requirements_ref.doc
- xrefs between segments- xrefs to other books in a collection
ibmdirector_intro_levels.dita
- xrefs/conrefs between peer topics+ key-based referencing (over URIs)
![Page 10: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/10.jpg)
10
#3 – Type (classify) your informationMS Word DITA
tasks
concepts
reference
+ content templates+ filenaming conventions
![Page 11: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/11.jpg)
11
#4 - Organize the segments into mapsMS Word DITA
+ {INCLUDETEXT} field codes+ Flat hierarchy and formatting
![Page 12: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/12.jpg)
12
#5 – Curate and organize the shared contentMS Word DITA
+ Words -> Document Props+ Blocks -> Bookmark Libraries+ Files -> Shared folders
+ Words -> Keydef maps-> Conref libraries
+ Blocks -> Keydef maps-> Conref libraries
+ Topics -> "Shared" designation
![Page 13: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/13.jpg)
13
#6 – Conditionalize the processing pipelineMS Word DITA
![Page 14: S doherty stc-new_england_interchange-2014_03](https://reader034.vdocuments.us/reader034/viewer/2022042607/5549b3e0b4c905fc7f8b47f7/html5/thumbnails/14.jpg)
14
#7 – Manage all the little pieces