STC New England Interchange 2014 Conference Presentation

1. 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 Architect
Stan@ModularWriting.com MathWorks Inc.
March 30, 2014 Stan.Doherty@MathWorks.com

2. 2
Arguments
A. Most best practices for modular writing can be implemented in any
publishing framework.
1. Segment your information
2. Encapsulate each segment
3. Type (classify) your information
4. Organize the segments into maps
5. Curate and organize the shared content
6. Conditionalize the processing pipeline
7. 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. 3
Information Architectures (Purist)
UNSTRUCTURED STRUCTURED (XML)
L
I
N
E
A
R
M
O
D
U
L
A
R
DocBook 4.x
S1000D
DocBook 5.x
DITA
MadCap Flare
MS Word
Open Office
FrameMaker (*.fm)
Wikis ?
Web Pages?
Blogs?

4. 4
Information Architectures (Practical)
UNSTRUCTURED STRUCTURED (XML)
L
I
N
E
A
R
M
O
D
U
L
A
R
DocBook 4.x
S1000D
DocBook 5.x
DITA
MadCap Flare
MS Word
Open Office
FrameMaker (*.fm)
Wikis ?
Web Pages?
Blogs?
MODULAR WRITING (UNOPTIMIZED)

5. 5
Information Architectures (Practical)
UNSTRUCTURED STRUCTURED (XML)
L
I
N
E
A
R
M
O
D
U
L
A
R
DocBook 4.x
S1000D
DocBook 5.x
DITA
MadCap Flare
MS Word
Open Office
FrameMaker (*.fm)
Wikis ?
Web Pages?
Blogs?
MODULAR WRITING (UNOPTIMIZED)

6. 6
Information Architectures (Practical)
UNSTRUCTURED STRUCTURED (XML)
L
I
N
E
A
R
M
O
D
U
L
A
R
DocBook 4.x
S1000D
DocBook 5.x
DITA
MadCap Flare
MS Word
Open Office
FrameMaker (*.fm)
Wikis ?
Web Pages?
Blogs?
MODULAR WRITING (UNOPTIMIZED)

7. 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, ePub
Kindle, HTML5
CONTENT MGT - - - - easyDITA
UNOPTIMIZED OPTIMIZED

8. 8
#1 - Segment your information
MS Word DITA

9. 9
#2 - Encapsulate each segment
MS 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. 10
#3 – Type (classify) your information
MS Word DITA
tasks
concepts
reference
+ content templates
+ filenaming conventions

11. 11
#4 - Organize the segments into maps
MS Word DITA
+ {INCLUDETEXT} field codes
+ Flat hierarchy and formatting

12. 12
#5 – Curate and organize the shared content
MS 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. 13
#6 – Conditionalize the processing pipeline
MS Word DITA

14. 14
#7 – Manage all the little pieces