Transcription

1 Getting a Handle on Release Management with DITA Fred Lass Senior Solutions Architect Astoria Software

2 Managing Multiple Releases Software control systems maintain i multiple l releases of their product with the ability to merge releases. eases How can Content Management Systems provide the same capabilities?

3 Release Management Methods and Options Traditional release management for documents use branch/merge. You identify the document, set a baseline, create a branch, make changes on both the trunk and branch. The branch is then merged with the trunk. Conflict Resolution Different changes in trunk and branch to same content requiring human attention are resolved resulting in a merged document. Optionally update trunk with merged document. So why not with DITA?

4 Using Branch/Merge on a single document Baseline Trunk Difference Base/Source/ Branch Edit Document Update Trunk with Merged Document Merged Create Merged Doc Conflict Resolution Branch Resolve Conflict Tickets Create Conflict Tickets Or Stare and Compare Edit Document

5 Is Branch / Merge really an option for DITA? Yes -- but the challenges are overwhelming All DITA documents are targets of many references. Topics are referenced by maps and relationship tables Common/collection files are targets of conref s from many topics Topics are referenced by <xref>s in other topics Topics are referenced by Related Links in other topics B hi j t t i i Branching just one topic requires special handling of references.

6 Branch/Merge gets complicated quickly Branching one topic Map.ditamap Concept.dita Common.dita <topicref>?????? <xref>????????? Topic.dita Source Topic.dita Base Topic.dita Branch Common.dita branch <ph conref>???

7 Imagine Branching a bookmap? Branching a bookmap Creates a unique silo of information easily thousands of files. All topics, graphics, common collections will be duplicated. All references (conref, xref, linkref, graphic ref) are re-written to keep the information silo valid. Merging the bookmaps Each individual object (bookmap, submaps, topics, graphics) will require unique attention. Handling of common files is tricky any changes coming from the merge will update files in topics and maps that were not part of the document set initially branched. Re-branching for maintenance of earlier releases adds to the mixture. Merging the branches means deciding on which links to maintain and which to change.

8 An Alternative Release Labeling Release Labeling makes use of your CCMS capabilities Versioning of documents and elements CCMS metadata that manages document and element relationships Release Labeling allows you to manage all releases within one document set Release Labeling utilizes document version time-stamps A Release Label indicates the time when any document (or element) has been approved for a specific release Release Labels are CCMS metadata, attached to any element The time-stamp t of a Release Label, will determine which h version of the element is associated with which specific release Release Labels on elements are inherited from ancestor elements

9 Release Labeling and Document Versioning Document (and element) Versioning Each time a topic is checked-in it is versioned A topic will be versioned multiple times between releases Documents go through change at a different rate Release Labeling utilizes version time-stamps A Release Label indicates the time when a document or element has been approved for release

10 Release Labels In General Release Labeling Release Labels have two components: Label Name (e.g. Astoria_Help_Rev_1.0) Label Date (e.g. 1/3/12 6:00 am PDT) Release Labels are metadata attached to elements Release Labels determine which version of an element is associated with that specific release Release Labels are inherited i within the document set as defined d by the highest level document An element inherits the Label/Date of the closest ancestor with the specific Release Label If an element has the same Release Label, the element s time-stamp will supersede the inherited time-stamp of its ancestor Release Label inheritance include all referenced items Conref targets inherit the Label/Date being applied by the referencing element Graphic files inherit the Label/Date of the referencing <image> element

11 Release Label Inheritance Release Label: Rev_1.0 2pm Inherit Label: Rev_1.0 2pm Inherit Label: Rev_1.0 2pm Release Label: Inherit Label: Rev_1.0 Rev_1.0 8am 8am

12 Referenced Topics versions and dates Inherit Label: Rev_1.0 2pm New Label: Rev_1.0 8am Inherit Label: Rev_1.0 2pm

13 Analyzing Specific Document Histories tk_workbench_login.dita has 9 versions. The Inherited Release Label is: Rev_1.0 2pm Version 1.3 (10/21/11) will be used when processing using Rev_1.0 Release Label. Versions 1 4 and up represent Versions 1.4 and up represent work for next revision Rev_2.0

14 Getting Started Setting Granularity Rate and ease of Release Management Highest level map Little or no reuse of map Changes between releases could be handled by duplication Submaps Subject to reuse Rate of change smaller after initial release and manageable Topics Robust reuse and referencing (as pointer and target) Almost all the content Rate of change constant most difficult to manage Common files and graphics Robust reuse as target tied to most releases Rate of change periodic Release management unpredictable. Confidential 14

15 Use case scenarios A Sample release management strategy Highest level map Each release will have its own map no need for labeling li Submaps and Topics Release controlled by Release Labels Common topics and graphics Release controlled by inheritance with option to label Graphic files Example: Bookmap / 3 Submaps / multiple Topics Release Labels (Astoria_Help_Rev_1.0) applied to submaps at different times. Confidential 15

16 Scenario #1: Updating previous release Using tk_workbench_login.dita Release Label on map is: Rev_1.0 2pm Compare version 1.9 with 1.3 to see what s changed. If version 1.9 s changes should be included in Rev_1.0 and the new modifications should be included in Rev_2.0, then make modifications to file, check-in and add Release Label for Rev_1.0 We ve already merged changes of the two Releases. Confidential 16

17 Scenario #1: Updating previous release If version 1.9 has content that is unique to Rev_2.0 and shouldn t be included in Rev_1.0, then do the following. Roll version 1.3 forward to be the current version so it can be changed. New version is 131i indicating continuation of 1.3 content. Confidential 17

18 Scenario #1: Updating previous release Make all my changes checking in the document a few times. Once approved, attach Release Label on the document (root element): Astoria_Help_Rev_1.0 which will have a time-stamp that includes version of this document. Confidential 18

19 Scenario #1: Updating previous release Now the document must be put back to its previous state. Version 1.9 is rolled forward to become the current version (I named the new version 2.0) so work can continue on Rev_2.0. Confidential 19

20 Scenario #2: Updating multiple releases Property Sheet of tk_workbench_login.dita shows 5 Approval Labels on the root element The two Rev_1.0 relate to a different book reusing this topic. The two for Astoria_Help_Rev_1.0 are the initial approval and after file was updated and re-approved. The last label is for Astoria_Help_Rev_2.0 Confidential 20

21 Scenario #2: Updating multiple releases New change for <cmd> in first step is for all releases. Astoria_Help_Rev_2.0: 14:53 PDT Astoria_Help_Rev_1.0: 14:47 PDT Confidential 21 Astoria_Help_Rev_1.0: 8:00 PDT

22 Scenario #2: Updating multiple releases Astoria_Help_Rev_2.0: 15:00 PDT Astoria_Help_Rev_2.0: 14:00 PDT Make change to current version creating version 2.3 Current version is starting point for Rev_3.0 no labeling required. Update Release Label for Astoria_Help_Rev_2.0 to include change (version 2.3). Confidential 22

23 Scenario #2: Updating multiple releases Release Rev_1.0 still needs to include the changes Options: Roll forward the current version of the document that was approved for Rev_ 1.0, make same change, attach new Rev_1.0 approval label, roll forward version that was previous current version to continue work on Rev_3.0. or... Set Release Label Rev_1.0 on <cmd> tag. Confidential 23

24 Managing changes options and considerations Each release will have its own Velocity of change Volume of changes Release Label granularity decisions Set on topic when velocity and volume are large Set on element when velocity and volume are small Will change depending on age of release.

25 Questions and discussion