Technical Memo

In the Episodes pattern language, http://c2.com/ppr/episodes.html, WardCunningham describes TechnicalMemo so:

: A Development Episode may intertwine with other activities demanding the attention of the Work Group. Further, some concepts may require quiet contemplation to absorb or may involve sufficient detail that they cannot be recalled without aid.
Therefore: Maintain a series of page-printable technical memoranda addressing subjects not easily expressed in the program under development. Focus each memo on a single subject and keep the text short and to the point. Carefully selected and well written memos can easily substitute for traditional comprehensive design documentation. The latter rarely shines except in isolated spots. Elevate those spots to technical memos and forget about the rest.

[Discussion moved from TooMuchDocumentation]

I am in agreement with RonJeffries (alert the media!) that the TechnicalMemo approach to design and project documentation is the best middle road. Ideally you'd want an amanuensis or MercenaryAnalyst to capture the most important design information, though they are few and hard to find. Still, it can pay off to get into the habit of putting down important design information, especially such things as discarded alternatives (that have resurfaced and been discussed three times already and probably will be again), architectural solutions to issues that aren't being implemented yet (YouArentGonnaNeedIt) but are in fact anticipated, rationale for decisions which were somewhat controversial at the time. and so on.

One place where I've found a need for documenting something for the future is in responding to questions about performance. "Why do you think you can make this fast enough to do 100 thousand people", they ask. You reply, in writing so you can remember it next time, "We have to go ten times faster. The new GemStone is touted as 4x faster, we're estimating two. When we tested on 5 CPUs, the system was 5x faster, we're estimating that with all 12, we'll be 8x. Finally, we see how to change the Bin architecture to cache year-to-date totals, which will save about half the system's I/O." Takes maybe one page. These are things you will do if you need to ... and not, if you don't. -- RonJeffries (going off to alert the media now ...)

This can apply to design/architectural issues as well as to other process issues (documenting platform, product feature, or resource allocation decisions, for instance). Email (suitably archived) can work fine, as can news/notes (or a combination). A WikiClone would also be good (though I'd prefer one of the variants with some sort of history mechanism). A lot of relatively low-level stuff can also be documented right in the code in the form of comments, but that's another topic... -- JimPerry

Microsoft do Technical Notes that I found pretty cool. They gave overviews of subsystems, drew information together from a variety of places. I found they worked quite well, from a consumer point of view (which isn't true of all documentation). I have written a few and found they work from a producer's point of view too.

I agree a Wiki-like system would be a good medium for these. It seems a natural PositionPaper?/CollaborativeDocument? kind of thing. -- DaveHarris

Something I think that was touched upon but not explicitly mentioned was the need to document how the design/architectural decisions were made (i.e. what were the ramifications of different approaches, why was one approach chosen over another, future issues, etc.). I don't think this information could be derived from current and previous versions of the code. It sounds like the TechnicalMemo approach might be a good way to store this information. -- AlanHecht

It would be ... and sometimes I do wonder why I did something. So I suppose someone else does also. But seriously, when have these questions ever really needed answering? Seems they're much less important than answering how things are? -- RonJeffries

These questions most commonly need answering when you're discussing what to do next. "This bit is broken, why don't we fix it this way?" Why documentation can tell you:

Because we already tried that solution, and it had the following drawbacks
Because we thought it had the following drawbacks
Gee, gosh, never thought of that before

If the project has had much turnover, without the why documentation, you may not know which of those three situations you're in.

-- BetsyHanesPerry

Ah, yes, turnover, I keep forgetting there are projects where everyone doesn't know everything. When ChryslerComprehensiveCompensation spins down to fewer folks, I'm sure we'll be asked to document some stuff. Many of the "why" things will be forgotten by then, I expect. At the same time, the system will be stable, clear, and what needs documenting will have it. Also see SpikeSolution. When we think of changing something, even if we tried it before, we don't assume we were right to reject it before, we just test it and see if we like it now. Odd, aren't we? -- RonJeffries

My initial response to when have these questions ever really needed answering was going to be that people might forget why they made the decisions in the first place. Upon further contemplation I realized, if I understand ExtremeProgramming correctly, that perhaps the architectural/design decisions are reflected in the UnitTests & AcceptanceTests and that improper changes will cause something to break (or suffer poor performance. I presume performance issues could be handled, if needed, in the test code). ContinuousIntegrationRelentlessTesting would ensure that not too much work was done before you ran across the reason as to why things were done a certain way. -- AlanHecht

Not quite. Every now and again we find ourselves looking at something and saying "Hmm, why did we do it that way." And if we can't find anyone who remembers, we don't know. It doesn't HURT us, because the code works, but it does make us wonder. I don't know whether it's worth writing more decisions down or not. It's a valid concern for which I haven't an answer, except that it hasn't ever hurt us. -- rj

But PaperGivesNoFeedback.

But paper helps avoid the BlindAlley.

This technical memo pattern sounds very useful! It is short, it describes history so it need not be up to date, yet it also describes the why of the system's design decisions.

I really wonder why this idea is not included in any of the XP books: it would take away much of the fear for XP, giving a new team trying to adopt XP the possibility to write some documentation when they have trouble unlearning old habits.

-- ArieVanDeursen

People might also get the wrong idea. I would rather explain to my superior why we don't document than try to explain a vague concept like an "acceptable level of documentation".

I agree that the "why" of things is probably not terribly important to document. Things change and what was rejected before may be a good idea now. Not only does the act of documenting the decision make one more likely to defend that point of view in the future but why be hampered with a document that tells me it's a bad idea? It's just one more thing to get in the way of innovation and we already have enough of those.

On the other hand, the what of things is important. If not for now for the next time you have to touch the code (or for the next team!). Taken to extremes you get BigDesign. However, as a simple mechanism for recording "concepts [that] may require quiet contemplation to absorb or may involve sufficient detail that they cannot be recalled without aid" it's a worthy candidate.

Finally, this type of document, seems to lend itself to what AlistairCockburn has described as setting you up for playing the next game. See SoftwareDevelopmentAsaCooperativeGame for more on this. -- PaulClanton?

Why not simply write each idea down on a StoryCard? Then, when the customer wants more speed, he just has to schedule one of these ideas. -- DougKing

This is just notes and cheatsheets and recipes.

CategoryDocumentation