using feature based metadata to improve maintainability 2009 05 04

© 2009 Xerox Corporation. All rights reserved.

Using Feature-Based Metadata to Improve MaintainabilityMike Rice


Model-C

No conditionalization


Model-D

Seat beltsWindshield wipers

(C)D


Publishing C and D

Model-C• No conditional contentModel-D• Include D

Applicability of C to D is implicit.

(C)D


Model-E

Seat beltsWindshield wipersRadioHeated seatsHydraulic brakesSun roof

(C)D

(C)

E

D


Publishing C, D, and E

Model-C• No conditional contentModel-D• Include DModel-E• Include D• Include E

Applicability of C and D to E is implicit.

(C)D

(C)

E

D


Model-F

Seat beltsWindshield wipersFour doorsChild safety locks (rear)Non-hydraulic brakesNon-heated seatsNo radio

(C)

E

D

F


Publishing C, D, E, and F

Model-C• No conditional contentModel-D• Include DModel-E• Include D• Include EModel-F• Include D• Include F

Content contains single conditions and implicit relationships.

(C)

E

D

F


Model-G

Seat beltsWindshield wipersSatellite radioHeated seatsHydraulic brakesTwo-doorTurboConvertible

(C)

E

D

F(C)

E

F

E G

GF G

D


Publishing E, F, and G

Model-C• No longer neededModel-D• No longer neededModel-E• Include D• Include EModel-F• Include D• Include FModel-G• Include D• Include G

Content contains compound conditions, obsolete conditions, and implicit relationships.

(C)

E

D

F(C)

E

F

E G

GF G

D


Model-H

Seat beltsWiperless windshieldSatellite radioHeated seatsHydraulic brakesFour doorsSport-utility

(C)

E

F

E G

GF G

D(C)

E

F

E G

G G HH

F G H

D

F H

D H


Publishing E, F, G, and H

Model-E• Include D• Include EModel-F• Include D• Include FModel-G• Include D• Include GModel-H• Include H

Some implicit relationships have become fragmented.

(C)

E

F

E G

G G HH

F G H

D

F H

D H


Rework and new for Model-G

Rework Rework

New


Rework and new for Model-H

ReworkNew


System effect of a bottleneck


Analysis by the author becomes the bottleneck!

“Technical debt” incurred unknowingly now needs to be paidBacklog of features to analyzeIf Paul was unable to clear his backlog, did the product ship with incomplete information, or was the product delayed?What happens if Paul leaves?What happens if a motorcycle or bus are introduced?What happens when more than one related product is introduced at one time?


Analysis does not add value

Value added Non-value added

Publishproduct

information

Rework existingcontent

Add new content

Analyze existingcontent


One aspect of the conflict

Quality, Cost, Deliveryrequirements met

Docs reflectdifferences in

product features

Common contentreused

Conditionalizefor each product

Describe product features


Product-based conditions

ProArise naturally from the progression of productsRelatively simple selection of conditions for the output

ConCompound conditionsRework grows as more products are supportedLong lead timesKnowledge of implicit conditions based on knowledge of product orderUse of prelaunch codenames can obscure the identity of the productObsolete product names add to clutterIf (when) errors creep in, the information set itself cannot be relied upon as the single source of truthAnalysis is thrown away


Hidden assumptions

Quality, Cost, Deliveryrequirements met

Docs reflectdifferences in

product features

Common contentreused

Conditionalizefor each product

Describe product features


What is feature-based metadata?

SeatBeltsWindshieldWipersRadioHeatedSeatsHydraulicBrakesSunRoofFourDoorsTwoDoorsChildLocksNOHydraulicBrakesNOHeated seatsNORadio

SeatBelts

Radio

SunRoof

WshldWipers

TwoDoors

ChildLocksFourDoors

NoRadio


Feature-based conditions

ProGreatly reduced rework – potentially zeroAnalysis is encoded into the information rather than being thrown awayReduced need to clean up legacy tagsShorter lead timesIncreased flexibility to respond to feature changesKeep up with scrum teamReduced use of compound conditionsUnambiguous tag names

ConDoes not fit neatly into DITA 1.0 metadataMany more conditions to manageSelecting conditions for publishing becomes much more complex


Yes, but…

Our documentation conditions are product-based.How will you keep track of all of those conditions????What about logical AND?


Existing product-based information

Implement feature-based conditions incrementallyContinue to use product-based conditions where you don’t need to touch the topicUse feature-based conditions for rework and new work.Use NO and AND naming convention• NOBrakes• WshldWipersANDHeadlights


Managing feature-based conditions

Unstructured FrameMaker• Master tags document

– Description of each feature– List of applicable products– Feature tag applied to both

• Product-specific copies with appropriate show/hide conditions applied

• Import conditions from product-specific tags document to FrameMaker book or document.

DITA• Ditaval• Master conditions topic

– Description of each feature– List of applicable products– Feature condition applied to both


Logical AND

Product tags represented logical ANDSometimes not needed in DITA• Nested elements can provide AND logicUse product conditions in the “fusebox”


Consider feature-based metadata…

…when product development is modular.…when development team uses agile process.…when new products cause you to rework existing content.…when you have compound product conditions.…when you find yourself repeating analysis.


Opportunities

Zero lead time product documentationCustom documentationCustom advertisement


Contact me

[email protected]

http://www.linkedin.com/in/michaeljrice

mailto:[email protected]

http://www.linkedin.com/in/michaeljrice

using feature based metadata to improve maintainability 2009 05 04

Documents

xerox corporation

g modelc

f modelc

conditional contentmodeld

publishing c

publishing e

modelg rework reworknew

eapplicability of c