Whether
your software development process is the antique waterfall
method or something more razzle-dazzle like the latest agile methodology you
have got to be creating some minimal levels of artifacts like documentation. That
is, of course, excepting those who continue to use no methodology, or the
methodology of “code and fix.” While much
attention has been paid to the excessive weight of artifacts, including
documentation, in recent years, little has been done to talk about strategies
which still meet the need for a common understanding of the software, while at
the same time minimize the effort required to create and maintain
documentation.

One
technique which deserves some attention is the idea of including documentation
by reference. In other words, refer folks to a more comprehensive source for
the detailed information while maintaining a reasonable summary in the document
itself.

An accepted practice

It’s
rare that I can find an opportunity to compliment government in something that
they’re doing. Trying to find examples of good practices from the government
often feels like looking for a needle in a field full of haystacks. While there
are many suggestions on how not to do things, there are a few really good ideas
on how to do things. Inclusion by reference is a great one of those ideas.

Recently
a church that I attend was cited for some minor fire code violations. They were
the kind that nearly every organization makes (according to the fire marshal
anyway). As a part of the process of resolving them I got very curious to
understand what the code said precisely. So I searched for the Indiana Fire
Code and the Indiana Electrical Code. (The violation was regarding the use of
un-fused multi-plug adapters.) What I found was amazing. The Indiana Fire Code
is a slight modification of the International Fire Code. They did an inclusion
by reference to include the entirety of the International Fire Code and then
modified minor sections which they didn’t agree with. What a great idea! The
Indiana Electrical Code followed the same pattern. It included the National
Electrical Code and made minor revisions.

This
allowed the legislature to write in more than a thousand pages of industry best
practices into law with less than 100 words. The exceptions took a few pages,
but the bulk of the work had been done for them.

This
struck me as a great way for architects, development leads, and senior
developers to communicate their message to other folks on the team. There’s a
precedent for including other material by reference; one that spans industries.
So instead of writing a short treatise on object inheritance you can simply
reference an article or book that thoroughly explains the topic and move on to
other topics and activities.

The dark lining

Despite
the readily apparent benefits there are a few pitfalls. The first challenge is
that having to look through multiple documents to find what you want can be
frustrating. This is easily solved by providing a meaningful summary of the
referenced work. The other challenge, however, is a bit more sinister.

In the
case of the examples above, both of the included documents are published by
standards bodies. Standards bodies want to make enough money to maintain their
operations. Because of that their standards are expensive. Purchasing the
National Electric Code and International Fire Code could easily cost $300. In
addition, I couldn’t find a downloadable form of either standard, which meant
waiting on the standards to actually arrive before I could get my answers. The
cost and delay represented a substantial barrier to my being able to use the
reference. (I could have driven downtown to review the State Fire Marshal’s
copies of these documents but that wasn’t practical either.)

In
your references for a development project you’re less likely to create a need
for $300 worth of standards; however, it is very tempting to reference a book
or a chapter in a book. While this is possible, it’s important to consider
whether the developer will have these references close at hand. If they won’t
have them close at hand, one of the questions becomes is it worth the frustration
to the reader if the reference is not close at hand. I’d argue that there are
some books that should be close at hand. Even in my public articles I reference
the works of Fred Brooks, Edward Yourdon, Steve McConnell, and others. I
realize that most developers do not own any of their works and yet I do it
anyway because they should.

No
matter how easy the reference is to get to a percentage of people will not
follow the reference, which is fine as long as they sufficiently understand the
concept by the short summary that has been provided.

A technology solution

To
minimize the impact of people not reading the referenced materials we can
leverage technology. The solution in the world we live in is to reference
permanently placed articles, postings, and information on the Internet. For
most people the Internet is just a click away from their desktop. Referencing
information on the Internet carries with it the highest probability that people
will be able to quickly and easily read the referenced material.

There
are, of course, times when the Internet is not available but those times are
getting less frequent every day. For small amounts of information while I’m
away from the office I can leverage my cell phone. Airplanes are now beginning
to get Wireless Internet service. Hotspots continue to pop up across the planet.
Getting connected to the Internet shortly after realizing you need some
information is becoming a reality almost everywhere.

A nice
side effect of linking to the Internet is that most of the materials to be
referenced are smaller and more focused. Where a book may cover rapid software
development and a chapter might cover techniques for rapidly developing client
applications, an article on the Internet is more likely to cover the specific
technique that you want to highlight.

Where and how to reference

If
you’re convinced that you want to start leveraging references in your documents
to reduce the amount of time that you’re writing documents (or because you like
the idea of less ceremony in your development methodologies), it’s time to
start adding references and to stop writing code.

The
first step is finding places to reference from. While requirements rarely have
references, except perhaps to government regulations where it’s necessary to
fully understand what compliance requirements may mean, design documents are
usually prime candidates for inclusion by reference. Design is largely the
assembly of a set of previously known techniques to solve a problem. Design
uses patterns (which can be referenced), techniques (which can be referenced),
and implementations (that can frequently be referenced.)

In
addition, detailed program specifications are also good candidates. Because
program specification documents are prescriptive in nature, including a
reference to an article or blog post which completes
the same task generally provides prescriptive guidance for the expected way
that the item will be completed.

That
leaves, however, the question of how to find the references. This is another
area where the current state of technology proves most helpful. By searching
for the concepts that you’re looking to convey in your favorite search engine
you can generally find something that will work for a reference. While this
initial investment of finding the right thing to reference isn’t completely
trivial it has a compounding effect that makes it even more effective over
time.

The
next time you need to refer a developer to the same thing you’ve already
referenced once, it will be easier to find—since you’ll likely go back to the
last place you referenced it an simply pick up the reference. Even if you go
back to the search engine you’ll likely remember the title in enough detail
that the right article or posting will jump out at you.

Collecting best practices

No one
wants to write more about something than they have to. Including other materials
by way of referencing them makes it possible to include large amounts of
information with relatively little effort. It forms a way of collecting the
industry best practices into your documents quickly and easily.