Rethinking Version Control for Agile Content


Published on

Version control systems do not work well for agile content, as this type of content is not built and published as a whole. If parts are changed, links may require changing as well. The presentation tries to outline a new paradigm for handling change in agile content.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Rethinking Version Control for Agile Content

  1. 1. rethinking version control Jang F.M. Graat - Content Agility - June 26, 2013
  2. 2. who’s talking ? Jang F.M. Graat studied physics, psychology, philosophy 25+ years in technical communications 10+ years in machine manufacturing domain “agile” philosopher addicted to challenge
  3. 3. one-dimensional version control One-dimensional version control does not fit the paradigm for intelligent content. It was a sound idea when information products were still single manuals for single products, but with the increasing modularization and reuse of content and variety of delivery channels and formats, the “past” and “future” cannot one-dimensionally be determined anymore.
  4. 4. modular documentation To start with, let’s have a look at modular documentation and the ways in which version control may impact information products that are built out of documentation building blocks. I am calling this section the past, as a lot of companies have been doing this for quite some time now.
  5. 5. component-based production Let’s have a look at component-based (i.e. modularized) production and see what we can learn from this that might help us in our technical documentation business domain.
  6. 6. product : assembly hierarchy car body chassis controls axleframe wheel engine shaft bearing flange The product is created from modules, which are built from assemblies, which are created out of subassemblies, which contain parts. There may be more levels, depending on the complexity of the product and its composing parts. The hierarchy follows a tree model.
  7. 7. changing an item version car body chassis controls axleframe wheel engine shaft bearing flangebearing axle chassis car frame shaft wheel body other cars Changing an item may have effects on other parts in the same assembly, and changes to the assembly may affect higher levels. A simple replacement may require revision of a large number of models, which in turn require changes in the production line. And because of the high level of reuse, other higher-level assemblies and eventually products are also affected.
  8. 8. change impacts everything item ID item ID item ID item ID parts ERP CAD 2D 3D VRML CAM finishing production material stock logistics manpower where used Each item is stored in a database along with all the information attached to it. For each item, there is (or should be) information about how the part becomes available (either purchasing or creating it - which involves CAM data and ERP info). All applicable technical details are attached to the item. In practice, the 3D model is often used as the hub, instead of using an empty item with just an ID to attach everything to. The upward link is given via the ‘where used’ query.
  9. 9. FFF : Form Fit Function To keep the impact of changes under control, the ‘FFF’ acronym was coined. It is not a strict definition but a guideline to help engineers decide whether a change to an item requires changes in the next level up or not. When the part keeps the same Form, Fit and Function, no changes in the upper level are required: the part can simply be replaced with the new one. What exactly constitutes the Form, the Fit and the Function depends on the item at hand.
  10. 10. FFF : pragmatic solutions In some cases, the FFF requirement can be reached by creating an adapter. In this way, the new micro-SIM can still be used in old cell phones that require a different form factor. As long as the chip is in the same location, it works on both types of phones. Similar pragmatic solutions are DVI to VGA converters, international power plugs, etc.
  11. 11. axle 1 shaft 1 bearing 1 flange 1bearing 2 axle 2 shaft 2 flange 2 minimizing change impact car 1 body 1 chassis 1 controls 1 frame 1 wheel 1 engine 1axle 2 Following the FFF rule, the impact of changes can be minimized. When a part is replaced by another part that complies on all three F’s, no further changes are required. The part can be replaced even halfway during production. Example: one SD card can be replaced by another SD card (brand) of the same memory size. In some domains (automotive, aerospace), such replacements will never be accepted: traceability requires at least another release of the item, which in turn invalidates the current release of the assemblies that incorporate the part.
  12. 12. topic 1topic 2 conref 1 xref 1 href 1xref 2conref 2 href 2 topic 2 content change management map 1 submap 1 submap 1 submap 1 topic 1 topic 1 topic 1 The CMS also plays a vital role as a Change Management System. In this respect, we should maybe adopt the FFF (Form Fit Function) rule or at least adapt it to the documentation world. When does a change in a doc part cause a change in the next level up ? When can a doc part be replaced without having the change ripple through the entire tree all the way up to the highest level ? Version control is not a matter of storing new versions of one particular item: it is also keeping those changes from causing changes in all the upper levels.
  13. 13. information products One step ahead of the past is the present. Instead of manuals as the main product, companies are increasingly interested in offering information through a variety of channels. I decided to skip the words “manual” and “online help” and talk about information products instead.
  14. 14. configuration management Real products contain lots of parts. Assembling a Volkswagen Golf takes thousands of prefabricated parts. The full list of required parts is called the Bill Of Materials. It is generated automatically by a process running down the design tree and listing all the items it finds, with the required quantities. Keeping that list up to date requires intelligent software for what is called configuration management.
  15. 15. overlapping configurations Machine manufacturers reuse the same basic parts to create a whole series of models. The models may have different body parts, different engines, different wheels, different transmissions, different controls. Many parts will remain the same between one model and the other. This complicates things for the configuration management, as new versions of each part will be developed and multiple versions of the same part live side by side in different products.
  16. 16. where are elements used ? One of the most important aspects of building massively modular products is where each item is being used. But along with the usage come the connections with other elements that may be required or optional. Think about cross-references, conrefs, implied knowledge etc. Each info element has connections to many other info elements.
  17. 17. info-product configurations Building information products out of the available items becomes a matter of configuration. Instead of writing manuals we are assembling them, not by copy-pasting but by configuring the final information product that is required. Multiple info products will co-exist in the same ecological niche. But with evolution of info elements and products following a sometimes erratic path, multiple versions of the same info element may have to co-exist.
  18. 18. information dependencies How can we hope to manage this bio-diversity, or info-diversity of the basic elements from which our info products are assembled? We need some kind of knowledge about applicability of the info elements. From the info product (configuration) we can then define dependencies on certain aspects. This can be visualized as connectors of a certain standard. An info product that requires a jack plug type connector cannot use the info element visualized above. This ties into the discussion of Form Fit Function earlier (concentrating on the Fit aspect).
  19. 19. version: 03 status : finished √ IDE : 6.4 x version: 01 status : finished √ IDE : 4.5 √ version: 02 status : finished √ IDE : 6.0 √ G D F G D A D E F G D A C B D E F G A C B D E F G D D 01 02 01 02 01 03 04 info-product CCMS 02 An example from one of the custom CCM systems I created for a customer. Updating the info product (configuration of elements) is done by entering the dependencies (various platform versions). The updating software finds newer versions of each info element and updates it when the applicability info matches the dependency requirements for the info product.
  20. 20. personalized information All good and well, but this more or less dynamic version control does not take information products out of the old paradigm, where the producer of the product determines what the product will look like. In tomorrow’s world, that may not be the best strategy, as customers want to determine what they need to know at any given point in time. We need to let go of the past that is still permeating everything in our present.
  21. 21. which modules are installed ? A B C D E F G H GUI a X X X X GUI b X X X GUI c X X library 1 X X X library 2 X X X X X X library 3 X X X X .NET X X X X SQL X X X PHP X X X X An actual example, simplified to fit the screen and not blow your minds away too much. A company produces a set of software modules that are dynamically bound together (on the customer system during installation of any of the modules) into a single environment with one look-and-feel. The customer needs the information on all installed modules, but should not see info on non-installed modules. There are between 5 and 50 out of a 100 modules on each individual system. Calculating the possible configurations leads to an astronomical number. It simply is not feasible to produce a personalized help system for each possible configuration.
  22. 22. can users figure it out ? Many producers of configurable or modularized software decide that it is not their problem to give the user exactly what they need. They just put messages all over the place, telling the customer to figure out what applies in their case. In practice, most end users have no idea about what is or is not installed (their IT department is in control of that) and do not stand a chance to do the right thing, especially if the documentation mentions all kinds of hidden technical details.
  23. 23. should users figure it out ? The final resort for many users is to just Google for the information they need. But with millions of hits from all over the internet, how reliable is the information in the end? Some companies simply let users do this and do not care about the results, as it is the user’s problem. But it is not. If your software cannot be made to work efficiently due to lack of reliable information, customers are going to Google a couple of times first, but then they will look for another product that will solve their problems without having to get info from the web all the time.
  24. 24. user-side configuration options Apart from the question of what is installed on each customer’s computer (which most customers do not know and cannot find out due to access restrictions imposed on them by their IT department), there are many options that can be switched on and off. If a feature is switched off, the information might not be applicable anymore, even if the module was installed. For a customer it does not matter whether the entire module was not installed or this one option was deactivated. Customers need information that fits their individual installation.
  25. 25. intelligent disclosure layer information elements (multiple versions) maps, indexes, cross-refs, search results product a product b product c This is where any build-time configuration for the help system breaks down by definition. We need to move from build-time configuration to on-the-fly use-time configuration. And this can be done by putting the right metadata in all the information elements, using the metadata in the products that link into this pool of information elements, and putting an intelligent disclosure layer between the two levels. The disclosure layer determines what is shown to each individual customer at any possible time.
  26. 26. c X X X dynamic toc, index, etc. information elements (multiple versions) a b If a new product (module) gets installed, the TOC, index and other disclosure elements can be automatically changed to fit the new information requirements. The new product may install new info elements but also reuse already existing ones. And if a user switches off certain features in one of the modules, the info elements that explain those features are filtered out and do not appear in the TOC, index etc. anymore.
  27. 27. dynamically changed linking information elements (multiple versions) a b c Cross-references should also follow this level of indirection, leading to one topic when module A and B are installed, but dynamically changed to another topic when module C is added at a later time. Search results should be filtered using the metadata in installed modules, so that only the relevant topics are shown, even though many more may be found by the full-text (or other) search engines in the help system.
  28. 28. give users what they need The end result should be an optimized user experience. The user has no need for information about modules and options that are not installed or switched off. They just need to do a job and need to know how it is done, on their system, right now. A fully personalized disclosure of information is, or should be, the goal of any information architect.
  29. 29. liquid information delivery
  30. 30. questions, reactions ? Jang F.M. Graat JANG Communication Amsterdam, NL @4everJang This, as usual in my more philosophical presentations, is a work in progress. I am interested in what people have to say about this. If there are existing systems that work more or less along the lines of what I have outlined in my presentation, I would love to know about them. I am hoping to develop these ideas further for future conferences.