s doherty stc-new_england_interchange-2014_03
DESCRIPTION
STC New England Interchange 2014 Conference PresentationTRANSCRIPT
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]
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)
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?
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)
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)
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)
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
8
#1 - Segment your informationMS Word DITA
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)
10
#3 – Type (classify) your informationMS Word DITA
tasks
concepts
reference
+ content templates+ filenaming conventions
11
#4 - Organize the segments into mapsMS Word DITA
+ {INCLUDETEXT} field codes+ Flat hierarchy and formatting
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
13
#6 – Conditionalize the processing pipelineMS Word DITA
14
#7 – Manage all the little pieces