Replace Documentation

There are ProblemsWithDocumentation. Therefore, before using documentation to solve a problem, consider alternatives that allow you to ReplaceDocumentation with something else. But the alternatives don't apply to all projects, nor are they applicable to every kind of document.

Note: Some people think of user manuals when they think of documentation. This page is referring to all documentation produced by a software project, not just user manuals.

Techniques for replacing documentation:

"Internal" documentation for use by the programming team:

Design documentation
Architecture documentation
- OralTradition -- I think the problems with this are obvious. -- Some problems are mentioned on the OralTradition page (under "resulting forces"). Please add any that we missed.
- Simply don't do it. Discover the necessary portions of the architecture as needed to make changes and don't pretend that any one person ever really knows what the "architecture" is.
Process documentation (includes build and deployment documentation)
- AutomateProcesses -- But remember that even the automated processes may need some documentation. People tend to easily forget what automated processes do, and exactly what does that daemon kick off once a week?
- ProjectWiki or TeamWiki is especially good at this, as it is easy to update when processes change (as they always do)

"External" documentation for use by others:

Technical Support Team documentation
QA Team documentation
- FrameworkForIntegratedTest
Requirements specification
- AutomatedAcceptanceTests -- This is cool for a small system, but in a large system, we would like to understand the problem domain before diving into the solution. Requirements allow us to scope the project and possibly even with priorities, prune them down to fit a schedule before implementing them. -- Have you ever seen a real project where this approach (requirements documents) actually works? -- Most big systems I have worked on required acceptance tests; the customers were not comfortable relying on the requirements documents either. I would probably quibble with the "automated" qualifier, though. A written test procedure that the customer can do himself seems to inspire more confidence that just hitting a button (although maintenance people tend to love automated diagnostics, which may be the same thing).
- FrameworkForIntegratedTest
- See AgileRequirementsDocumentation
API documentation
- JavaDoc -- Technically, JavaDoc is a form of documentation ~JimLittle
User documentation
- EnlargeUserBase
- TrainUsersFirst -- Cannot train commercial software customers
- SelfDocumentingUserInterface -- Fine for simple form-based and database reporting UI's -- The reality for most software programs is the users do not read the documentation.
ContextSensitiveHelp?

Techniques for improving documentation:

Related Discussion: (see also: http://c2.com/cgi/wiki?search=Document)

Testimonials:

(please contribute experience-based reports of this approach succeeding)

Anti-testimonials:

(please contribute experience-based reports of this approach failing)

Arguments against:

This page flies in the face of common sense and standard software engineering practice. Calling it a ProtoPattern is potentially harmful... what if an inexperienced programmer read this page and took it as fact? This page needs justification: describe the problems related to documentation, show that they are in fact inherent to documentation, and then show how the alternative solutions work better. Without justification, this page is not just wrong, it's harmful.
There aren't any problems with documentation, so there's no need to replace documentation. All of the problems gathered so far in ProblemsWithDocumentation are in fact problems with unprofessional people. Both with those in charge of writing documentation and with those who use the documentation. None of them are problems inherent to the nature of documentation.
JDK's java doc, database product documentations, compiler documentation, man pages, etc., etc., CANNOT be substituted by any of the techniques proposed above. How about that: you don't know how find command works, well, go read the SelfDocumentingCode. You don't know what a function in the library is supposed to accomplish, go and read the code, or try to communicate directly with the author, or whatever.
"Architecture documentation...don't pretend that any one person ever really knows what the 'architecture' is." I simply can't disagree with this statement more. Many times I have worked on products that desperately needed an architecture design and one person to be the architect. I have sometimes been the architect and sometimes willingly given up that role to someone else whose technical expertise I trusted. The result of an architecture design is a document that describes the architecture in words, expressions, and imagery that all team participants can implicitly understand. -- MartySchrader
The following are among the items that can't be replaced : database documentation that describes the meaning of fields in the database and relationships between tables, system flow among various processes (even given that you have tests for the system flow the why is lost in the code), description of why one path was chosen over another when there are two equally good paths at first glance (if applicable), product marketing and sales training doc (assuming you are selling your software and not developing it internally). Using code as the doc is definitely a drawback when OptimizingCode?. The best optimizations happen at a higher level then any one module. This requires an understanding of the system as a whole. -- FrankMcGeough

Arguments in favor:

I believe the justification requested here is invalid; you do not require justification for inactivity. What is the justification for doing documentation for the first place?
Only ReplaceDocumentation with things that work better. The techniques above are suggestions, not requirements. If none of them work better in your situation, don't ReplaceDocumentation.

I love reading documentation. Well written documentation is a blessing for my soul. I loved TurboPascal help pages, I was thrilled by the wonderfully written man pages for HP-UX (in fact many were BSD derived at that time) and every Unix that I've worked with since then, the excellent documentation for Oracle, Excell help pages and many many others. If any of the above technique would be applied to me as a user for selling me whatever undocumented product I would hate it. TrainUsersFirst? You sure must be kidding, train somebody else, not me, no thanks, I want to use a well documented product and I still have plenty of choices. Do you expect me to work on a project where I have to read the implementation of source code so that I'd be able to program against an undocumented and ever changing, ever refactored interface? Well, sometimes I might have to do just that , one never knows under these market conditions, but I sure don't like it. It's definitely a project smell. I just had to do it the recently, because of the lousy job they did it on some parts of the JDK where JavaDoc is worse than nothing. They might have gotten some bad advice so they cut back on technical writers and instead ship the JDK with the source code. In contrast I never ever had the need to do something like this with Unix or Oracle, whatever it says in their docs, it is complete and the software behaves exactly as described in its docs. As a matter of fact the man pages for Unix or the HTML docs for Oracle are a lot better than many written books, and they are free and handy to use.

On the other hand I hate to write documentation because I am just lousy at it, but if I have to do it and I don't do it well, I won't dare to complain about ProblemsWithDocumentation instead of acknowledging my lack of professionalism. I also have the chance to work in a couple of projects where the user documentation was taken care of by professional tech writers. If you think they are expensive and you can deliver better value without them, well, you only have my condescending smile. If you think you have ProblemsWithDocumentation I have one simple solution for you: find yourself a professional tech writer, likewise if you run into problems with software you better find yourself professional developers. No other fooling around with fancy substitutes (like the ones described above ) is going to help you anyway. Therefore, best of luck with this page and find your way of reinventing a squared wheel and test if it works better for you in whatever situations, but make sure that you don't throw away some solid things that are common sense in software development. -- CostinCozianu

I refactored this page on 20 Sept 2001. In refactoring, I attempted to move all points made in the discussion into DocumentMode above. I condensed all similar arguments into a single bullet point. If you want to correct my changes, the original page is at ReplaceDocumentationOriginal. -- JimLittle

Note: An anonymous donor has complained that the author of this page didn't sign it. So I'll fess up: I'm the original author. But this page has benefited from the contributions of many people, most of whom didn't sign their contributions. Thanks to all of you; if you want credit, please add your name here:

Contributors: JimLittle

Discussion: (Please discuss merits of specific techniques on the page devoted to that technique.)

Let's discuss that the concept of this page is still flawed. Why do we need to replace documentation? Not to mention the almost tautology replace something that doesn't work very well with something that works better. We could then all give up on wiki and replace it with a single page DoSomethingThatIsGoodForYou?. And the be sure thing is very funny.

What's the javadoc doing in here? Replace documentation with other documentation? Some techniques enumerated here cannot be discussed in their pages, because they are not techniques for replacing documentation. It is as simple as that. Enumerating them here is misleading to say the least. -- CostinCozianu

Costin, I don't understand your hostility here. You're right, this page is almost a tautology. That's why I was surprised to see you react so violently to it. I know from experience that some of the above techniques can work better than written documentation; perhaps not all of them, but some. But I didn't say that would work better in all cases... what I said was, "Replace documentation when you can, here's some possible techniques." What's so bad about that?

The more I program, the more I find that things that I thought were "obviously" true are actually not true. Our profession (software engineering, not computer science) is filled with popular myths, but very few meaningful studies. In the absence of those studies, I think we have to be open to trying unusual ideas in our own projects and seeing first-hand whether they work or not.

If you have an experience report about trying to ReplaceDocumentation and failing, that would be a very valuable contribution: please add it. If not, however, please consider the DifferenceBetweenTheoryAndPractice. -- JimLittle

Well, I thought I clearly documented in the original page where ReplaceDocumentation will not work. You lost that in refactoring, you still haven't defined what are the contexts where you think ReplaceDocumentation might work, and why (what are the logical reasons behind the proposed solutions).

For example what are the logical reason why you think that acceptance tests can replace documenting (writing it down) the specification, or how unit tests can replace design documentation (or documenting the interfaces between modules). Both examples are not known as alternatives for replacing documentation but for other things, so just asserting that they can serve as well for replacing documentation is at least invalid as an argument.

I like that you say that our profession is filled with popular myths, I entirely agree with this. But what you are doing here is creating more myths, for which we have even less study, and less logical arguments behind it (it worked for me is a good start, but is not by far good enough). We have to be open to unusual ideas, but not at the expense of our customers, and not without proper logical argumentation. -- CC

You know, some of us know how to learn from other people even if they aren't logical and rigorous. ;-)

Hi, Jim. Nice job you did of refactoring this page. Much cleaner now. I hadn't followed the tirades, so I visited the old page and saw what you were faced with.

What I still miss on this page is that you are referring to "internal" and "intermediate" documents, not externally mandated ones such as a user manual. This should be highlighted, because I didn't get that on the first read.

Also, I liked these sentences that didn't make it here on the first refactoring (but are here now :-): "Users have only two ways of telling what the system does. They can read the documentation, or they can experiment. Developers have a third option: they can read the code."

Don't worry about people who think you are nuts for advocating out loud what you are busy thinking, just keep going. They'll advocate out loud what they are thinking, also. -- Alistair

I also love reading documentation and find the whole premise of this page to be an affront to all that I admire about good documentation. To me good docs can not only describe and educate but provide context from which the user can build their understanding.

If a project does not boast great documentation maybe the project itself is not worthy, I certainly wouldn't want to be involved in development of a project whose worth, value, function and form is not expressed in the complimentary documentation.--SimonArmstrong

I think all complementary documentation should be complimentary documentation. Sorry, I just could not resist.

As I see it, the problem is not the documentation per se, but the kind of documentation we generate. I surely love to read a well-written manual, as I enjoy reading a well-written book, but surely HATE to wade through a wall sized UML diagram or a inch thick design "document". Most of the time I have to go look into the code anyway.

[What if the UML is nicely hierarchical using PacketDiagrams? to organize the ClassDiagram s and included ("see figure 1"...) in the well-written manual similar to any well-written text. Besides what's wrong with also printing out the whole diagram and covering the wall? Telecom NOCs, Nuclear control rooms, heck NASA launch control workers have no issue with large wall sized schematics and views why should programmers, who are some of the most advanced knowledge workers be skiddish about diagrams, even if they are large? Of course code is the most important to drill down to but code embodies higher-order relationships which I think some form of CirclesBoxesAndArrows is needed to make clear at a glance rather than untangling nested if statements]

Documentation for the end-user is surely a must, documentation for the sake of the process or to show that we're doing something is a waste of time and resources. -- RafaelAlvarez

Users have only two ways of telling what the system does. They can read the documentation, or they can experiment.

Let me provide an alternate viewpoint. The users already know what a system should do. What they need to know is how to make the system do what it should do. A clear, intuitive system requires little or no documentation to explain how the users can run the system. An unclear system often requires extensive manuals to explain how to operate the system. Like comments in source code, user manuals provide an indication that a user interface should be probably be redesigned to provide more clarity.

Hmmm. Users know what a system should do? This is true for trivial apps or for apps that already have a solid model in users heads but certainly not true for much else. I still remember watching someone who was told to use a mouse and picked up the mouse to try and move the cursor. The fact that a mouse works by rolling it on the mousepad was not something that user found intuitive. [Note: TeachMeToSmoke] Does that make a mouse a bad design? Nope. Did the user know what the system should do? Yep, it should move the cursor on the screen when I move the mouse (just not that way). This is an extremely trivial example but a demonstration that users knowing what the system should do is not a substitute for much of anything. What about users that work with totally foobar'd existing systems? Should our software emulate those just because that's what they think a system should do? What if I can make their job 10x easier but it requires them to think in a different way? As for lack of documentation that is essentially where most people find themselves today. The doc accompanying most systems is useless. However, a large set of people would find complete accurate doc very helpful.

There's some disagreement about how this page should be categorized. CategoryJoke? CategoryAntiPattern? CategoryProtoPattern? CategoryProcessPrinciple?

CategoryDocumentation