Discussion on:

Generate development documentation with the inclusion by reference method

The downloadable version of this article is available here:
http://techrepublic.com.com/5138-3513-6052659.html

What method do you use to create documentation for your development projects? Do you think the inclusion by reference outlined in the download/article is feasible in your organization? Do you have a better method?

As the bulk of the software I have dealt with has been custom developed, I am not sure what generic documentation that I should expect to include.

The environment I have worked in most recently is the US federal government, which tends to be quite document heavy. Even though each document does contain references to outside material, coverage of the custom material runs 100+ pages. I guess I fail to see what environments exist where any significant portion of the documentation can be replaced with previously written material.

Can anyone provide examples where common design documents (requirements, design, test plan, user manual, etc.) have had signficant section replaced by references to other documents?

Unix man pages do just that, half of what you need to know is in another man page. It's a miserable way of doing things. Feel free to bring the content from another source, but never force the developer (who in this instance is a user) to look at anything else. All help must be contextually useful at any given time, otherwise it has no value in and of itself, and wastes the person's time to boot.

J.Ja

An example I can think of immediately is a requirements document that references the fuel loading tables in the specifications for an aircraft. Another example is referencing other MIL-STD documents that give very detailed information on, for example, military imaging formats. That same goes for RFC documents. (I still use MIL-STD-498 for documentation when it is up to me what we use.) A lot of time, developers need information that is outside the scope of the particular document are writing and including references to detailed information elsewhere is invaluable.

I can see where if I had reference to a document that showed the overall system design and/or place a particular program fit in, that would be very helpful. I could imagine a standard reference tag that would allow one to open up the reference(s) as needed while working on maintaining the program. Sometimes it's harder to see what else is affected by a specific program in the chain, if you don't know what the chain is. Maybe that could be included in the program documentation, but I think that would become unwieldy. Even including the name/location of other documentation would be a step up from what I've seen some places, where you have to search a documentation directory to find the relevant information.