SIGDOC Newsletter
September 2005
:: Volume 6, Number 3
Features
Parallel Design and Development for Documentation Projects
By Rob Pierce
robertp@us.ibm.com
It is common for a company or organization to be working on different
versions of a particular deliverable concurrently. This is commonly known
as parallel development. If two product development cycles and release
dates are planned in the future, one in six months and one in eighteen
months, then a likely scenario of developing two versions of a product
at the same time may occur. In software development, there are not only
feature releases but service releases and hotfixes or patches. How changes
are tracked and included between one version and the next, can become
a complex management task. And the level of granularity on managing changes
between one version and another applies not only at the product level
but for each particular source file in a product. While some files are
required by different components in a product to correctly function such
as a DLL or EXE, even html, text or other document files need to be tracked
and managed between product releases and differing versions.
The term parallel development is a bit generic in that it typically
encompasses all aspects of product development including design, development
or implementation,
debugging, testing, and documentation.
To be more specific, since the development cycle includes design, development
or implementation, testing, debugging, and documentation, there will
be iterative development and stages or cycles of types of work at different stages.
back to top
Parallel development can occur within any of the following groups for
a given release:
- Architectural Design
- Development/Implementation
- Testing and debugging
- Documentation
A combination of tooling and process is required to successfully
work in this type of environment. For example, a change management
system to manage the ongoing newly submitted defects and enhancement requests,
an asset management system that can store and maintain multiple
versions of source files, a test management system to formalize/organize,
track
and maintain test plans, test cases and the specific instances
tests,
are all tools that can help manage parallel development. Enforcing
policies for use of the tools or mandating them by less automated means helps
ensure that the tools are used in a consistent manner to ensure
that
software and documentation development can be tracked correctly
and consistently.
In Development, a good example of how change is managed in parallel
development is a core file that needs to be modified to fix a
customer-raised defect
from a previous product release. The issue is analyzed by Development
and resolution is proposed; upon acceptance or approval, the
solution is designed and implemented in order to provide a fix. This fix
might be delivered to a customer in the form of a hotfix – which
is often a fixed file that can be copied to replace the version
of a file in the
product already installed. But this type of solution is not typically
a long term solution.
More commonly, a collection of fixes is combined and included
in a patch, also known as a service release. A service release
is
usually not a full
version of a product that can be installed but a collection
of fixed files for a product that can be installed on a system that
already has
the product installed. Usually, a service release can only
be installed on a system with the product already installed. Some
service releases
however do in fact contain the entire product and can be installed.
And to complicate the picture further, some installations require
the user
to uninstall previous versions of the product before a newer
version can be installed. Not all products enable users to
upgrade directly
by installing updated versions that replace the earlier version.
back to top Hotfixes, patches and service release are intended to supply
customers with bug or defect fixes. Enhancements to the product
or new features
are not typically included in such releases.
New features are more commonly planned and release in new
versions of a product.
All such product releases also apply to documentation.
In Documentation, a good example of how change is managed
in parallel development is a documentation source file
that needs
to be modified.
Many documentation defects or requests for enhancement
are issues raised by customer.
Just as in Development, to fix a customer-raised defect
from a previous product release, an issue is analyzed
by the information
developer and
a resolution is proposed and reviewed by a stakeholder,
such as
the Developers of a given component or feature. Upon
acceptance or approval, the resolution
is documented and added to the documentation source
files in order to provide a fix.
While documentation is usually updated for a full
product release, it is not always updated in a
service release
or patch. Release
notes or
service release notes are possible options for
supplying documentation updates between releases. Release notes
are one of the most
dynamic documentation deliverables prone to change
and the complexity
of changing content from
one release to the next.
So, a fix will likely be delivered to a customer
in the form of a release note or patch release
note. If
the
updated documentation
supported a
fix to be supplied as a hotfix, then the documentation
may in fact
be included as a text file with the hotfix. But
just as for a source file
supplied in a hotfix, this is not a long term
solution.
back to top Service release notes are usually intended to
briefly describe the collection of Development
fixes being
supplied and
does not include fixes to Documentation.
This is different than a full product release
in which documentation defects are included
in Release
Notes,
depending on the severity
of the problem.
It is interesting to note that while not a
common solution, updated documentation could
in fact
be provided like
a service release
and could be installed
as a collection of fixed files for updated
technical content that could be installed
on a system that
already has the
product installed.
There
are some forms of this type of dynamic content
available in the market but to the best of
my knowledge is
not commonly implemented.
New documentation which in a sense is a new
feature is usually not provided to customers
until the
next full
release is
available.
All of these scenarios help explain why
parallel development is the norm in software
development
organizations.
Developers, writers, and testers all
are tracking change on an ongoing basis,
analyzing
issues,
proposing resolutions,
and providing
fixes.
Managers are providing guidance for
schedules and versions in which the fixes are to
be resolved and provided
in releases.
Much of the process complexity is in
not always being able to know what
are the
dependencies between one
change and
the next.
back to top Certainly an asset management system
is necessary to maintain multiple
versions of files. Versioning
enables
product
stability and enables
multiple versions to be both worked
on and built into a version of
the product.
One solution is for work on the
files for
each product version to be on separate
branches.
For example,
an asset management
system enables
the maintenance of multiple versions
of all the files in a product so
that the
development
of
a hot fix,
a service
release,
and
two new full
product versions can all proceed
concurrently.
Developer and Writers can work
on different versions of source
files
without destabilizing
other versions.
Eventually,
different
versions
can be merged and changes in
different versions resolved. There are tools
that support content
merges, but
merging is more
common for code files
than for documentation files.
Still, it is possible to merge
the changes of different versions
of
a file for documentation.
For example,
a given task might
have been documented
one way for a given release,
but a new step was
added during a service release.
A hotfix may have been
provided since
the full
release that
also included an updated task
description that applied to
a fixed code file.
For the next
full product release
it would
be feasible
to merge
the hot fix documentation content
with the service release content
and roll
the changes
into the
product documentation
as an update
to that
documentation source file.
While not exactly a merge example,
it is a form
of merging.
Parallel development is very
complex and prone to confusion.
It raises
the possibility
of
conflicts in file content
that will cause
new issues.
Using tools that enable change
and asset management as well
as developing
policies
or a process
for how
parallel
development
is to proceed greatly
enhances the opportunity for
success.
back to top
|
