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.