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:

"External" documentation for use by others:

Techniques for improving documentation:

Related Discussion: (see also:



Arguments against:

Arguments in favor:

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?


EditText of this page (last edited October 1, 2006) or FindPage with title or text search