modularity ~ the key to reusereuse ~ guided authoring a structure provides guidance for authoring...
TRANSCRIPT
Copyright © A&O Consultancy Ltd. 2016
Modularity ~
The key to reuse
management
Copyright © A&O Consultancy Ltd. 2016
Synopsis
A review of reuse, from a content management
perspective
Introduce the issues that face reuse management
A return to modularity
Solutions to improve reuse management
Business perspectives
Copyright © A&O Consultancy Ltd. 2016
Reuse review 1
Reuse of ‘common’ content ~ warnings and cautions
Reuse of ‘difference’ content ~ product names, content
Reuse by profiled content
Reuse by referenced content
Copyright © A&O Consultancy Ltd. 2016
Reuse review 2
Profiledcontent
Referencedcontent
Common content reuse ✘ ✔ ︎
Difference content reuse ✔ ︎ ✔ ︎
Copyright © A&O Consultancy Ltd. 2016
Reuse review 3
Important to consider implications of ‘common’ or
‘difference’ referenced content
Naming strategy for common content can be specific ~
SafetyInfo/PBatteryCaution
Naming strategy for difference content should be
generic ~ ProductInfo/KywProductName
Copyright © A&O Consultancy Ltd. 2016
An anatomy of reuse 1
0
25
50
75
100
Frontmatter IntroductionFunctionalDescription Registers
Signal Descriptions
Semiconductor reference manual
Copyright © A&O Consultancy Ltd. 2016
An anatomy of reuse 2
Reuse is not uniform across a document
No single reuse mechanism ~ topicsets, chunking, keys
and scoped keys all play a part
How does an author immediately know how many
reuse instances there are for a particular topic?
Copyright © A&O Consultancy Ltd. 2016
Reuse ~ guided authoring
A structure provides guidance for authoring
DITA provides guidance for profiled content, DITAVAL
elements, @product, @platform, @audience ...
DITA provides the mechanisms for referenced content,
but no guidance for authoring
Copyright © A&O Consultancy Ltd. 2016
4D of reuse management
1D ~ Profiled content
2D ~ Referenced content: source, target, map or maps
3D ~ Time: content reuse over the lifetime of a product
4D ~ Personnel: author, editor, reviewer, translator
Copyright © A&O Consultancy Ltd. 2016
iMac ~ Then and Now
What content reuse
over 18 years?
© C
opyr
ight A
pple
2016
Copyright © A&O Consultancy Ltd. 2016
Modularity review 1
John M. Carroll, Minimalism
‘The Nurnberg Funnel’ ~ Reading in any order
Robert E. Horn, Information Mapping
Eventually lead to DITA and topic based authoring
Copyright © A&O Consultancy Ltd. 2016
Modularity review 2
J. M. Carroll and R. E. Horn worked with monolithic
tools, before DITA
DITA is a two stage process ~ author then disseminate
Do the original principles behind DITA only apply to
disseminated content?
Can, or should, the principles also apply to the content
during authoring?
Copyright © A&O Consultancy Ltd. 2016
A modular DITA topic!?
Copyright © A&O Consultancy Ltd. 2016
Profiled content
Copyright © A&O Consultancy Ltd. 2016
Referenced content
Copyright © A&O Consultancy Ltd. 2016
Profiled & referenced
Copyright © A&O Consultancy Ltd. 2016
Modularity & reuse
Pros Cons
Profiled content
Very modularPoor reuse
management
Referenced content
Good reuse management
Poor modularity
Profiled & referenced
Good reuse management
Some modularity
Copyright © A&O Consultancy Ltd. 2016
Restore modularity
Additions to the content model:
ReuseItems ~ guide referenced content authoring
ResolvedItems ~ a ‘passport’ for a topic
ResolvedReferences ~ adds ‘signposts’ to sources to
every map
Copyright © A&O Consultancy Ltd. 2016
ReuseItems 1
New area, outside <body/> contains one or more
<ReuseItem/>, standard <title/> & <desc/>, follows
topic content model
Can define <PreferredKeys/>
Move core attributes up to element content level to
guide author ~ element to reuse and one or more id
Include example ~ author literally copies example
Copyright © A&O Consultancy Ltd. 2016
ReuseItems 2
‘Break into’ content model ~ a series of <li/> would not
need a parent <ul/> or <ol/>
Note: NOT an attempt to redefine DITA mechanisms
Tools could use content and copy to attributes
Provides metadata ~ explain what it is, why it is, and
demonstrate how to use it
Copyright © A&O Consultancy Ltd. 2016
ResolvedItems 1
New area, outside <body/>
The processor resolves referenced content
Idea is to capture the resolution, for each build, and
store it within the topic, or a ‘parallel’ file
Capture resolved referenced content
Capture exactly where and how each build uses topic
Copyright © A&O Consultancy Ltd. 2016
ResolvedItems 2
An author, reviewer, translator immediately knows how
the topic is used, and how many times
No need for on-the-fly resolution
Pick a build from a list ~ the resolved content appears
Topics would be stand-alone, and not need a supporting
map
Copyright © A&O Consultancy Ltd. 2016
ResolvedItems 3
Important that it is read only, hence ‘parallel’ file
Authors MUST NOT be able to edit this area
Authors can make applicable preferences ~ default
build, hide old builds
Copyright © A&O Consultancy Ltd. 2016
ResolvedReferences 1
New area that follows content, <topicref/> ...
The processor resolves referenced content
Idea is to capture the resolution, for each build, and
store all the sources of referenced content within every
map and sub-map
Every map knows every build it is a part of, and any
referenced content sources for that build
Copyright © A&O Consultancy Ltd. 2016
ResolvedReferences 2
An author attaches a new topic to any map
The map states which build or builds it is a part of
Also defines the available reference content sources for
each build
The author immediately knows whether it is the correct
map, and can see the available reference content
Copyright © A&O Consultancy Ltd. 2016
Business perspectives 1
A reviewer can compare the current product with the
previous
An author can immediately identify whether review
comments would impact other uses of the topic
A documentation team can competently define and
execute a reuse strategy
Copyright © A&O Consultancy Ltd. 2016
Business perspectives 2
An information architect can track the reuse strategy ~
maps provide top-down, this offers bottom-up approach
A translation company can immediately see if there are
going to be issues or problems
A safety officer can track warnings and cautions and see
where each is used
Copyright © A&O Consultancy Ltd. 2016
Summary
Reuse is extremely important, and therefore reuse
management is, too
Referenced content breaks topic modularity
Restore modularity, and the author experience is greatly
enhanced
Copyright © A&O Consultancy Ltd. 2016
Thank you for your interest
Contact details: linkedin.com/in/djbhollis