The document discusses the need for more dynamic and personalized approaches to version control and documentation. It argues that traditional one-dimensional version control is no longer suitable given modular, reusable content and varied delivery formats. It proposes taking cues from component-based production to manage interdependent information elements. Key aspects include minimizing change impacts using "Form Fit Function" rules and intelligently disclosing only relevant information based on a user's specific configuration. The goal is "liquid information delivery" that dynamically adapts information to fit each user's individual needs.
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.