While software is being created, its design and requirements frequently undergo a number of revisions. Constantly updating the documentation to match is expensive. Therefore, wait until the end of the project before creating documents not required to create the software itself. Examples include architectural overviews, design walkthroughs, and user manuals.
Known Uses:
Testimonials:
- TitaniumIt? used this approach on the DenaliProject when our contract ended. We created a detailed 20-page walkthrough of the system that described the history and current state of the project, how to get started on a new machine, what the directories and scripts of the project were for, a general architectural and design overview, and the coding standards and techniques we used. It took one person about three days to create that document.
-
- It was the finest documentation I've ever seen a project produce: up-to-date, informative, and with lots of juicy tidbits about where the project had been and where we thought it should go. There was a whole section devoted to "future challenges." (In the interests of full disclosure, I should mention that I was the author, and it was my idea to do things this way. So this testimonial is biased. Heavily.)
-
- I love writing good documentation, and I used to be quite religious about it. But I don't believe the document was ever read. That's something I've noticed about documentation in general. So now I preach ReplaceDocumentation instead. --JimLittle
- When I was working on the project I could only write SillyDocs?, but when I was finished with it I could give sensible, deep assertions about what was going on - JohnCarter
Anti-Testimonials:
- You must be kidding. I have seen so many of these "document after the fact" attempts go bad that I can't even begin to count them. In particular, the last medical device project I was on had [has, as of Feb 03] a major league problem in the interaction among system components. There is no single component of the instrument that knows the Go/No Go status of all the subsystems, so certain components take off on their own as soon as they see stimulus. I did an architectural design over two years ago on how the instrument needed to be structured and organized through an Instrument Manager component, but the documentation was never completed and the idea didn't "catch on." Two years go by and the damnable thing still doesn't work.
-
- There was no documentation when I started on this project. The project was fairly mature. Now I'm documenting and I have up to 91 FixMeTags in the documentation already. Major policy decisions weren't documented and sometimes different and conflicting policies are implemented in various parts of the code. - JohnCarter
- "Design" documents written after the fact are really only useful to meet audit requirements. Decisions made early on have been long forgotten. I am not much of a believer in design documents written beforehand, either. It is simply much more productive to create a set of ProgrammerTests and AcceptanceTests that actually verify the design than to create an overwhelming stack of paper of questionable accuracy.
- Backloading all documentation, especially user docs, to the end of the process is begging for trouble. It creates a bottleneck and increases the liklihood that something will be forgotten. Rather, each piece should be documented as its completed. See UserDocsInXp.
[Note: This page can't be safely listed as a proto-pattern because of the dangerous assumptions about the nature of documentation (verb) made by some of the proponents. Let's wait a while until there is more input on this before categorizing a pattern here.]
A ProtoPattern is something that "has worked successfully for the author, and is written in some pattern form, but it does not yet reflect the experiences of multiple people who also know this pattern." I think this qualifies, so...
CategoryProtoPattern
See: ReplaceDocumentation, VideoTapingDesign, DocumentsFirstCodeLater
CategoryDocumentation
Document Last