1© 2014 The MathWorks, Inc.
Best Practices in Modular Writing: Parallel
Modeling in Word and DITA
Stanley Doherty, Ph.D.
O...
2
Arguments
A. Most best practices for modular writing can be implemented in any
publishing framework.
1. Segment your inf...
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....
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
Information Architectures (Practical)
UNSTRUCTURED STRUCTURED (XML)
L
I
N
E
A
R
M
O
D
U
L
A
R
DocBook 4.x
S1000D
DocBook...
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...
7
Demo Environment
CONTENT Sun ISV Integrations Sun ISV Integrations
FILESYSTEM WINDOWS/MAC WINDOWS/MAC
SOURCE FORMAT .doc...
8
#1 - Segment your information
MS Word DITA
9
#2 - Encapsulate each segment
MS Word DITA
ibmnetcool_intro_requirements_ref.doc
- xrefs between segments
- xrefs to oth...
10
#3 – Type (classify) your information
MS Word DITA
tasks
concepts
reference
+ content templates
+ filenaming conventions
11
#4 - Organize the segments into maps
MS Word DITA
+ {INCLUDETEXT} field codes
+ Flat hierarchy and formatting
12
#5 – Curate and organize the shared content
MS Word DITA
+ Words -> Document Props
+ Blocks -> Bookmark Libraries
+ Fil...
13
#6 – Conditionalize the processing pipeline
MS Word DITA
14
#7 – Manage all the little pieces
Upcoming SlideShare
Loading in …5
×

S doherty stc-new_england_interchange-2014_03

399 views

Published on

STC New England Interchange 2014 Conference Presentation

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
399
On SlideShare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
4
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

S doherty stc-new_england_interchange-2014_03

  1. 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. 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. 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. 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. 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. 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. 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. 8 #1 - Segment your information MS Word DITA
  9. 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. 10 #3 – Type (classify) your information MS Word DITA tasks concepts reference + content templates + filenaming conventions
  11. 11. 11 #4 - Organize the segments into maps MS Word DITA + {INCLUDETEXT} field codes + Flat hierarchy and formatting
  12. 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. 13 #6 – Conditionalize the processing pipeline MS Word DITA
  14. 14. 14 #7 – Manage all the little pieces

×