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

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

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?

ight A

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

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

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

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

Documents

authoring tool training...

rapiddeveloper - cortona3d...provides 3d visual knowledge...

authoring software

multimedia authoring

k-dcp engineering toolchain booklet · 2020-06-09 ·...

president's malaria initiative technical guidance ·...

irs provides guidance on next year's medicare surtax

multimedia authoring

microsoft excel 2016 basic authoring and testing guide...

web authoring

microsoft word 2016 basic authoring and testing guide...

national statistician’s guidance...national...

april 2019 display screen equipment (dse) guidance screen...

teaching and learning as multimedia authoring:...

dol provides important guidance regarding “persuader...

microsoft excel 2016 basic authoring and testing guide...

technical advisory group provides guidance to usaid in...

nhs charities: evaluation guidance - think npc · nhs...

introduction to multimedia · like c and java. multimedia...

authoring assistance in technical communication authoring...