© 2009 Xerox Corporation. All rights reserved.
Using Feature-Based Metadata to Improve MaintainabilityMike Rice
© 2009 Xerox Corporation. All rights reserved.
Publishing C and D
Model-C• No conditional contentModel-D• Include D
Applicability of C to D is implicit.
(C)D
© 2009 Xerox Corporation. All rights reserved.
Model-E
Seat beltsWindshield wipersRadioHeated seatsHydraulic brakesSun roof
(C)D
(C)
E
D
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
Model-F
Seat beltsWindshield wipersFour doorsChild safety locks (rear)Non-hydraulic brakesNon-heated seatsNo radio
(C)
E
D
F
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
Model-G
Seat beltsWindshield wipersSatellite radioHeated seatsHydraulic brakesTwo-doorTurboConvertible
(C)
E
D
F(C)
E
F
E G
GF G
D
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
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?
© 2009 Xerox Corporation. All rights reserved.
Analysis does not add value
Value added Non-value added
Publishproduct
information
Rework existingcontent
Add new content
Analyze existingcontent
© 2009 Xerox Corporation. All rights reserved.
One aspect of the conflict
Quality, Cost, Deliveryrequirements met
Docs reflectdifferences in
product features
Common contentreused
Conditionalizefor each product
Describe product features
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
Hidden assumptions
Quality, Cost, Deliveryrequirements met
Docs reflectdifferences in
product features
Common contentreused
Conditionalizefor each product
Describe product features
© 2009 Xerox Corporation. All rights reserved.
What is feature-based metadata?
SeatBeltsWindshieldWipersRadioHeatedSeatsHydraulicBrakesSunRoofFourDoorsTwoDoorsChildLocksNOHydraulicBrakesNOHeated seatsNORadio
SeatBelts
Radio
SunRoof
WshldWipers
TwoDoors
ChildLocksFourDoors
NoRadio
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
Yes, but…
Our documentation conditions are product-based.How will you keep track of all of those conditions????What about logical AND?
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
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
© 2009 Xerox Corporation. All rights reserved.
Logical AND
Product tags represented logical ANDSometimes not needed in DITA• Nested elements can provide AND logicUse product conditions in the “fusebox”
© 2009 Xerox Corporation. All rights reserved.
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.
© 2009 Xerox Corporation. All rights reserved.
Opportunities
Zero lead time product documentationCustom documentationCustom advertisement
© 2009 Xerox Corporation. All rights reserved.
Contact me
http://www.linkedin.com/in/michaeljrice