Modularity ~ The key to reuse management

Transcription

1 Modularity ~ The key to reuse management

2 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

3 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

4 Reuse review 2 Profiled content Referenced content Common content reuse Difference content reuse

5 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

6 An anatomy of reuse Semiconductor reference manual Frontmatter Introduction Functional Description Registers Signal Descriptions

7 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?

8 Reuse ~ guided authoring A structure provides guidance for authoring DITA provides guidance for profiled content, @audience... DITA provides the mechanisms for referenced content, but no guidance for authoring

9 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

10 imac ~ Then and Now What content reuse over 18 years? Copyright Apple 2016

11 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

12 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?

13 A modular DITA topic!?

14 Profiled content

15 Referenced content

16 Profiled & referenced

17 Modularity & reuse Pros Cons Profiled content Referenced content Profiled & referenced Very modular Good reuse management Good reuse management Poor reuse management Poor modularity Some modularity

18 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

19 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

20 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

21 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

22 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

23 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

24 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

25 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

26 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

27 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

28 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

29 Thank you for your interest Contact details: linkedin.com/in/djbhollis