modularity ~ the key to reusereuse ~ guided authoring a structure provides guidance for authoring...

Copyright © A&O Consultancy Ltd. 2016

Modularity ~

The key to reuse

management


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


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


Reuse review 2

Profiledcontent

Referencedcontent

Common content reuse ✘ ✔ ︎

Difference content reuse ✔ ︎ ✔ ︎


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


An anatomy of reuse 1

0

25

50

75

100

Frontmatter IntroductionFunctionalDescription Registers

Signal Descriptions

Semiconductor reference manual


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?


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


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


iMac ~ Then and Now

What content reuse

over 18 years?

© C

opyr

ight A

pple

2016

http://www.apple.com/imac/then-and-now/




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


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?


A modular DITA topic!?


Profiled content


Referenced content


Profiled & referenced


Modularity & reuse

Pros Cons

Profiled content

Very modularPoor reuse

management

Referenced content

Good reuse management

Poor modularity

Profiled & referenced

Good reuse management

Some modularity


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


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


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


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


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


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


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


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


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


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


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


Thank you for your interest

Contact details: linkedin.com/in/djbhollis

https://www.linkedin.com/in/djbhollis

https://www.linkedin.com/in/djbhollis

modularity ~ the key to reusereuse ~ guided authoring a structure provides guidance for authoring...

Documents