SlideShare ist ein Scribd-Unternehmen logo
1 von 30
Downloaden Sie, um offline zu lesen
rethinking version control
Jang F.M. Graat - Content Agility - June 26, 2013
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
liquid information delivery
questions, reactions ?
Jang F.M. Graat
JANG Communication
Amsterdam, NL
jang@jang.nl
www.jang.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.

Weitere ähnliche Inhalte

Ähnlich wie Rethinking Version Control for Agile Content

EDM Systems In Depth Review
EDM Systems In Depth ReviewEDM Systems In Depth Review
EDM Systems In Depth ReviewGlen Alleman
 
SideKick: every author´s assistant
SideKick: every author´s assistantSideKick: every author´s assistant
SideKick: every author´s assistantOvidius GmbH
 
Next Generation Component Management - Altium Designer
Next Generation Component Management - Altium DesignerNext Generation Component Management - Altium Designer
Next Generation Component Management - Altium DesignerAltium
 
Common Project Mistakes (And How to Avoid Them)
Common Project Mistakes (And How to Avoid Them)Common Project Mistakes (And How to Avoid Them)
Common Project Mistakes (And How to Avoid Them)Inductive Automation
 
Production Kanban Software Productoo 2018 | Smart Factory
Production Kanban Software Productoo 2018 | Smart FactoryProduction Kanban Software Productoo 2018 | Smart Factory
Production Kanban Software Productoo 2018 | Smart FactoryProductoo Software
 
Chris's editorial march '13
Chris's editorial march '13Chris's editorial march '13
Chris's editorial march '13Victoria Smith
 
Michele_Brun-Final
Michele_Brun-FinalMichele_Brun-Final
Michele_Brun-FinalMichele Brun
 
IT 200 Milestone One Guidelines and Rubric Scenario .docx
IT 200 Milestone One Guidelines and Rubric  Scenario .docxIT 200 Milestone One Guidelines and Rubric  Scenario .docx
IT 200 Milestone One Guidelines and Rubric Scenario .docxchristiandean12115
 
Practical machine learning
Practical machine learningPractical machine learning
Practical machine learningFaizan Javed
 
New Developments in New-Product Development
New Developments in New-Product DevelopmentNew Developments in New-Product Development
New Developments in New-Product DevelopmentPTC
 
dairy farm mgmt.pptx
dairy farm mgmt.pptxdairy farm mgmt.pptx
dairy farm mgmt.pptxMusabInamdar2
 
The Future of PLC Programming by WonderLogix
The Future of PLC Programming by WonderLogixThe Future of PLC Programming by WonderLogix
The Future of PLC Programming by WonderLogixsalesbuddy
 
How to estimate the cost of a Maximo migration project with a high level of c...
How to estimate the cost of a Maximo migration project with a high level of c...How to estimate the cost of a Maximo migration project with a high level of c...
How to estimate the cost of a Maximo migration project with a high level of c...Mariano Zelaya Feijoo
 
XYZ Fast Prototyping MGMT 3405 1 Definition – Fa.docx
XYZ Fast Prototyping MGMT 3405  1  Definition – Fa.docxXYZ Fast Prototyping MGMT 3405  1  Definition – Fa.docx
XYZ Fast Prototyping MGMT 3405 1 Definition – Fa.docxjeffevans62972
 
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...ijcax
 
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...ijcax
 
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...ijcax
 
Mobica White Paper -Digital Instrument Cluster
Mobica White Paper -Digital Instrument ClusterMobica White Paper -Digital Instrument Cluster
Mobica White Paper -Digital Instrument ClusterSchuyler Kennedy
 

Ähnlich wie Rethinking Version Control for Agile Content (20)

EDM Systems In Depth Review
EDM Systems In Depth ReviewEDM Systems In Depth Review
EDM Systems In Depth Review
 
SideKick: every author´s assistant
SideKick: every author´s assistantSideKick: every author´s assistant
SideKick: every author´s assistant
 
Next Generation Component Management - Altium Designer
Next Generation Component Management - Altium DesignerNext Generation Component Management - Altium Designer
Next Generation Component Management - Altium Designer
 
Common Project Mistakes (And How to Avoid Them)
Common Project Mistakes (And How to Avoid Them)Common Project Mistakes (And How to Avoid Them)
Common Project Mistakes (And How to Avoid Them)
 
Productoo Smart Factory Suite
Productoo Smart Factory SuiteProductoo Smart Factory Suite
Productoo Smart Factory Suite
 
Production Kanban Software Productoo 2018 | Smart Factory
Production Kanban Software Productoo 2018 | Smart FactoryProduction Kanban Software Productoo 2018 | Smart Factory
Production Kanban Software Productoo 2018 | Smart Factory
 
Chris's editorial march '13
Chris's editorial march '13Chris's editorial march '13
Chris's editorial march '13
 
Michele_Brun-Final
Michele_Brun-FinalMichele_Brun-Final
Michele_Brun-Final
 
IT 200 Milestone One Guidelines and Rubric Scenario .docx
IT 200 Milestone One Guidelines and Rubric  Scenario .docxIT 200 Milestone One Guidelines and Rubric  Scenario .docx
IT 200 Milestone One Guidelines and Rubric Scenario .docx
 
Practical machine learning
Practical machine learningPractical machine learning
Practical machine learning
 
New Developments in New-Product Development
New Developments in New-Product DevelopmentNew Developments in New-Product Development
New Developments in New-Product Development
 
dairy farm mgmt.pptx
dairy farm mgmt.pptxdairy farm mgmt.pptx
dairy farm mgmt.pptx
 
The Future of PLC Programming by WonderLogix
The Future of PLC Programming by WonderLogixThe Future of PLC Programming by WonderLogix
The Future of PLC Programming by WonderLogix
 
How to estimate the cost of a Maximo migration project with a high level of c...
How to estimate the cost of a Maximo migration project with a high level of c...How to estimate the cost of a Maximo migration project with a high level of c...
How to estimate the cost of a Maximo migration project with a high level of c...
 
XYZ Fast Prototyping MGMT 3405 1 Definition – Fa.docx
XYZ Fast Prototyping MGMT 3405  1  Definition – Fa.docxXYZ Fast Prototyping MGMT 3405  1  Definition – Fa.docx
XYZ Fast Prototyping MGMT 3405 1 Definition – Fa.docx
 
Medicine For World
Medicine For WorldMedicine For World
Medicine For World
 
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
 
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
 
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
Developing Product Configurator Tool Using CADs’ API with the help of Paramet...
 
Mobica White Paper -Digital Instrument Cluster
Mobica White Paper -Digital Instrument ClusterMobica White Paper -Digital Instrument Cluster
Mobica White Paper -Digital Instrument Cluster
 

Mehr von Jang F.M. Graat

Faster than Agile - Proposal for Lavacon 2015
Faster than Agile - Proposal for Lavacon 2015Faster than Agile - Proposal for Lavacon 2015
Faster than Agile - Proposal for Lavacon 2015Jang F.M. Graat
 
From user assistance to user guidance: Information apps
From user assistance to user guidance: Information appsFrom user assistance to user guidance: Information apps
From user assistance to user guidance: Information appsJang F.M. Graat
 
Dynamic links using (meta)data
Dynamic links using (meta)dataDynamic links using (meta)data
Dynamic links using (meta)dataJang F.M. Graat
 
Maximising the effect of progressive disclosure
Maximising the effect of progressive disclosureMaximising the effect of progressive disclosure
Maximising the effect of progressive disclosureJang F.M. Graat
 
Progressive Disclosure - Putting the User in Control
Progressive Disclosure - Putting the User in ControlProgressive Disclosure - Putting the User in Control
Progressive Disclosure - Putting the User in ControlJang F.M. Graat
 
XPath-based transformations in structured FrameMaker
XPath-based transformations in structured FrameMakerXPath-based transformations in structured FrameMaker
XPath-based transformations in structured FrameMakerJang F.M. Graat
 
Driving DITA off the Map
Driving DITA off the MapDriving DITA off the Map
Driving DITA off the MapJang F.M. Graat
 
Advanced techniques for conversion to structured FrameMaker
Advanced techniques for conversion to structured FrameMakerAdvanced techniques for conversion to structured FrameMaker
Advanced techniques for conversion to structured FrameMakerJang F.M. Graat
 
Create your own $35 CMS in Structured FrameMaker
Create your own $35 CMS in Structured FrameMakerCreate your own $35 CMS in Structured FrameMaker
Create your own $35 CMS in Structured FrameMakerJang F.M. Graat
 
Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen.
Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen.Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen.
Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen.Jang F.M. Graat
 
Nur der Nutzer weiss, was der Nutzer noch nicht weiss - Progressive Disclosure
Nur der Nutzer weiss, was der Nutzer noch nicht weiss - Progressive DisclosureNur der Nutzer weiss, was der Nutzer noch nicht weiss - Progressive Disclosure
Nur der Nutzer weiss, was der Nutzer noch nicht weiss - Progressive DisclosureJang F.M. Graat
 
Changing the engine without stopping the rickshaw
Changing the engine without stopping the rickshawChanging the engine without stopping the rickshaw
Changing the engine without stopping the rickshawJang F.M. Graat
 
How I killed the webmaster - and got away with it
How I killed the webmaster - and got away with itHow I killed the webmaster - and got away with it
How I killed the webmaster - and got away with itJang F.M. Graat
 
How to become a trainer - and make lots of $$$
How to become a trainer - and make lots of $$$How to become a trainer - and make lots of $$$
How to become a trainer - and make lots of $$$Jang F.M. Graat
 
Getting your hands dirty - How tech authors may be able to survive in the mac...
Getting your hands dirty - How tech authors may be able to survive in the mac...Getting your hands dirty - How tech authors may be able to survive in the mac...
Getting your hands dirty - How tech authors may be able to survive in the mac...Jang F.M. Graat
 
CADD: What can DITA learn from CAD?
CADD: What can DITA learn from CAD?CADD: What can DITA learn from CAD?
CADD: What can DITA learn from CAD?Jang F.M. Graat
 

Mehr von Jang F.M. Graat (20)

XSLT for Authors
XSLT for AuthorsXSLT for Authors
XSLT for Authors
 
Faster than Agile - Proposal for Lavacon 2015
Faster than Agile - Proposal for Lavacon 2015Faster than Agile - Proposal for Lavacon 2015
Faster than Agile - Proposal for Lavacon 2015
 
Out of-control
Out of-controlOut of-control
Out of-control
 
Flowcharting DITA
Flowcharting DITAFlowcharting DITA
Flowcharting DITA
 
From user assistance to user guidance: Information apps
From user assistance to user guidance: Information appsFrom user assistance to user guidance: Information apps
From user assistance to user guidance: Information apps
 
Minimalism to the MAX
Minimalism to the MAXMinimalism to the MAX
Minimalism to the MAX
 
Dynamic links using (meta)data
Dynamic links using (meta)dataDynamic links using (meta)data
Dynamic links using (meta)data
 
Maximising the effect of progressive disclosure
Maximising the effect of progressive disclosureMaximising the effect of progressive disclosure
Maximising the effect of progressive disclosure
 
Progressive Disclosure - Putting the User in Control
Progressive Disclosure - Putting the User in ControlProgressive Disclosure - Putting the User in Control
Progressive Disclosure - Putting the User in Control
 
XPath-based transformations in structured FrameMaker
XPath-based transformations in structured FrameMakerXPath-based transformations in structured FrameMaker
XPath-based transformations in structured FrameMaker
 
Driving DITA off the Map
Driving DITA off the MapDriving DITA off the Map
Driving DITA off the Map
 
Advanced techniques for conversion to structured FrameMaker
Advanced techniques for conversion to structured FrameMakerAdvanced techniques for conversion to structured FrameMaker
Advanced techniques for conversion to structured FrameMaker
 
Create your own $35 CMS in Structured FrameMaker
Create your own $35 CMS in Structured FrameMakerCreate your own $35 CMS in Structured FrameMaker
Create your own $35 CMS in Structured FrameMaker
 
Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen.
Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen.Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen.
Dita Spezialisierung - Wie machen Sie es, und warum Sie es machen sollen.
 
Nur der Nutzer weiss, was der Nutzer noch nicht weiss - Progressive Disclosure
Nur der Nutzer weiss, was der Nutzer noch nicht weiss - Progressive DisclosureNur der Nutzer weiss, was der Nutzer noch nicht weiss - Progressive Disclosure
Nur der Nutzer weiss, was der Nutzer noch nicht weiss - Progressive Disclosure
 
Changing the engine without stopping the rickshaw
Changing the engine without stopping the rickshawChanging the engine without stopping the rickshaw
Changing the engine without stopping the rickshaw
 
How I killed the webmaster - and got away with it
How I killed the webmaster - and got away with itHow I killed the webmaster - and got away with it
How I killed the webmaster - and got away with it
 
How to become a trainer - and make lots of $$$
How to become a trainer - and make lots of $$$How to become a trainer - and make lots of $$$
How to become a trainer - and make lots of $$$
 
Getting your hands dirty - How tech authors may be able to survive in the mac...
Getting your hands dirty - How tech authors may be able to survive in the mac...Getting your hands dirty - How tech authors may be able to survive in the mac...
Getting your hands dirty - How tech authors may be able to survive in the mac...
 
CADD: What can DITA learn from CAD?
CADD: What can DITA learn from CAD?CADD: What can DITA learn from CAD?
CADD: What can DITA learn from CAD?
 

Kürzlich hochgeladen

Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1DianaGray10
 
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationUsing IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationIES VE
 
UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7DianaGray10
 
Designing A Time bound resource download URL
Designing A Time bound resource download URLDesigning A Time bound resource download URL
Designing A Time bound resource download URLRuncy Oommen
 
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...DianaGray10
 
Comparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioComparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioChristian Posta
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfAijun Zhang
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfDianaGray10
 
Bird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemBird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemAsko Soukka
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPathCommunity
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfinfogdgmi
 
AI You Can Trust - Ensuring Success with Data Integrity Webinar
AI You Can Trust - Ensuring Success with Data Integrity WebinarAI You Can Trust - Ensuring Success with Data Integrity Webinar
AI You Can Trust - Ensuring Success with Data Integrity WebinarPrecisely
 
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online CollaborationCOMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online Collaborationbruanjhuli
 
VoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXVoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXTarek Kalaji
 
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesAI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesMd Hossain Ali
 
How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?IES VE
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfJamie (Taka) Wang
 
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IES VE
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024D Cloud Solutions
 
OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureEric D. Schabell
 

Kürzlich hochgeladen (20)

Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1Secure your environment with UiPath and CyberArk technologies - Session 1
Secure your environment with UiPath and CyberArk technologies - Session 1
 
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve DecarbonizationUsing IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
Using IESVE for Loads, Sizing and Heat Pump Modeling to Achieve Decarbonization
 
UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7UiPath Studio Web workshop series - Day 7
UiPath Studio Web workshop series - Day 7
 
Designing A Time bound resource download URL
Designing A Time bound resource download URLDesigning A Time bound resource download URL
Designing A Time bound resource download URL
 
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
Connector Corner: Extending LLM automation use cases with UiPath GenAI connec...
 
Comparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and IstioComparing Sidecar-less Service Mesh from Cilium and Istio
Comparing Sidecar-less Service Mesh from Cilium and Istio
 
Machine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdfMachine Learning Model Validation (Aijun Zhang 2024).pdf
Machine Learning Model Validation (Aijun Zhang 2024).pdf
 
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdfUiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
UiPath Solutions Management Preview - Northern CA Chapter - March 22.pdf
 
Bird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystemBird eye's view on Camunda open source ecosystem
Bird eye's view on Camunda open source ecosystem
 
UiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation DevelopersUiPath Community: AI for UiPath Automation Developers
UiPath Community: AI for UiPath Automation Developers
 
Videogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdfVideogame localization & technology_ how to enhance the power of translation.pdf
Videogame localization & technology_ how to enhance the power of translation.pdf
 
AI You Can Trust - Ensuring Success with Data Integrity Webinar
AI You Can Trust - Ensuring Success with Data Integrity WebinarAI You Can Trust - Ensuring Success with Data Integrity Webinar
AI You Can Trust - Ensuring Success with Data Integrity Webinar
 
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online CollaborationCOMPUTER 10: Lesson 7 - File Storage and Online Collaboration
COMPUTER 10: Lesson 7 - File Storage and Online Collaboration
 
VoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBXVoIP Service and Marketing using Odoo and Asterisk PBX
VoIP Service and Marketing using Odoo and Asterisk PBX
 
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just MinutesAI Fame Rush Review – Virtual Influencer Creation In Just Minutes
AI Fame Rush Review – Virtual Influencer Creation In Just Minutes
 
How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?How Accurate are Carbon Emissions Projections?
How Accurate are Carbon Emissions Projections?
 
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
activity_diagram_combine_v4_20190827.pdfactivity_diagram_combine_v4_20190827.pdf
 
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
IESVE Software for Florida Code Compliance Using ASHRAE 90.1-2019
 
Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024Artificial Intelligence & SEO Trends for 2024
Artificial Intelligence & SEO Trends for 2024
 
OpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability AdventureOpenShift Commons Paris - Choose Your Own Observability Adventure
OpenShift Commons Paris - Choose Your Own Observability Adventure
 

Rethinking Version Control for Agile Content

  • 1. rethinking version control Jang F.M. Graat - Content Agility - June 26, 2013
  • 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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.
  • 30. questions, reactions ? Jang F.M. Graat JANG Communication Amsterdam, NL jang@jang.nl www.jang.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.