Replace Documentation Original
Replace Documentation OriginalOriginal text of ReplaceDocumentation before I refactored it, 20 Sept 2001. -- JimLittle
Warning: This page is a work in progress. Please take it with a grain of salt.
There are significant ProblemsWithDocumentation. Therefore, replace documentation with something that works better.
There's been some confusion about the above statement. Only ReplaceDocumentation with things that work better. The techniques below are suggestions, not requirements. If none of them work better in your situation, don't ReplaceDocumentation.
Techniques for replacing documentation:
Related Discussion: (see also: http://c2.com/cgi/wiki?search=Document)
Yep, it's an AntiPattern:
This page is harmful. Documentation is something that's absolutely needed. It is an integral part of any decent and professional software product.
Maybe the coding cowboys here, can get away with their user base, even if they "ReplaceDocumentation" with one of the things they enumerated above. Don't do it like them. Maybe they got some problems with their documentation and in their ignorance they decided that it was the documentation that needed to be replaced with something that supposedly works better. I would have replaced (fired) the documentation writers. Anyway, if something like documentation has problems, it should be obvious for anyone that it is not the idea of documentation per se that suffers, but the amateurs who created the documentation not clear, out of sync, etc, etc ...
If they want to make software products that lack documentation, let them be happy. For the rest of the world this belongs to CategoryJoke, CategoryAntiPattern. In the meantime, I'd suggest that this page cries DeleteMe, and also cries GiveUpOnAmateurism?.
There are two different kinds of documentation. Documentation for users (which describes the product itself), and documentation for developers (which describes the code that implements it). Which are you saying is "absolutely needed"? Both?
I am not to argue why documentation is needed and I won't argue anymore, like I won't argue why the circle is round. This is common sense and a well-established practice in software development. If one doesn't know why, then one has to study. Both documentation for users and documentation for developers are needed in the general case, and documentation for users is a must for any piece of software that is supposed to be the work of professionals.
In some small cases it might be arguable that documentation for developers is not needed, I rather doubt that. But counter-examples are plenty: JDK's java doc, database product documentations, compiler documentation, man pages, etc., etc., all are for developers. They 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 need 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.
Some of these things are what I'd call "user documentation", even though the users may well be developers. The manpage for find was not written for the benefit of people working on the code of find. I am not a developer for most of the libraries whose functions I use.
The claim being made by the XP people is not that all documentation is useless, but that developer documentation (in the sense I'm talking about) is generally the wrong way to preserve information. This claim may be right or wrong, but it's not wrong-by-inspection however often you say it is. How about offering some arguments against it, rather than just disagreeing?
The example with find's man page or JDK's javadoc is too easy to put in a "user documentation" category. Just because some documentation is not written within team directly involved, it doesn't mean that it is "user documentation" and not "developer documentation". It is being used by developers with the sole purpose of constructing software based on other software, just the same you would use a module written by a colleague, and you don't want to inspect his code, in order to be able to use that. You only want to have a clear documentation of the interface to his module and how to use it. Do you want to study the man page for find or do you want to inspect the code for find, it's clear you want the first option. What if find was not provided by the system and was written by one of your colleague in the course of the project, you wouldn't have had then the excuse that it's user documentation and not "developer documentation" whatever that is supposed to mean?
You've forgotten that you were the one to provide arguments for ridiculous claims made on this page (don't forget that users are still included here, see TrainUsersFirst, and EnlargeUser?). Your claims are not wrong-by-inspection, but they are assumed wrong until otherwise proven because there's a large body of knowledge about software development that is overwhelmingly against your claims. It's futile to construct here a book on what is documentation, what are the categories of documents a project may produce, and so on, so forth. There are books for it.
If you want to disagree and to revolutionize the body of knowledge, please go ahead, but you have to bring very good arguments, not just to throw claims and pretend that one cannot refute your claims. One doesn't want to waste time in doing so. Only after you brought substantial arguments for ReplaceDocumentation, one can invest time in discussing/debunking them, and so on, and so forth. And while you're at it, please don't forget that if some projects are able to stuck all the engineers in one room, and institute OralTradition, SelfDocumentingCode and other good stuff as the way to do it (or really?), other projects fit in one bloody building, so some of the techniques pretended to be able to ReplaceDocumentation are absolutely useless.
At last, we have some reasons! Thank you.
I am not going to try to prove that "developer documentation" should be abolished, because in fact I don't think it should be. I didn't write the body of this page; I'm just commenting on some unnecessarily insulting comments made about it. So, with that in view, let's take a look.
It's true: the distinction between "user documentation" and "developer documentation" is not as clear-cut as it might be. (Nor are most distinctions, actually...) There are, however, some relevant differences.
The relationship between the user of a typical piece of software and the people who wrote it is very asymmetrical. The user typically can't communicate directly with the authors and ask specific questions. The user generally has no use for documentation that goes deeper than the interface, since s/he can't change the software or even have much direct influence on how others change it. These are forces that argue for written documentation. The developer, however, is often in the same room as all the other people who worked on the software, and can talk to the people who wrote any given part of it. The developer may have a use for information that goes beyond the interface; not, of course, so as to be able to write evil code that makes illegal assumptions, but so as to be able to improve the interface or suggest improvements in it. These facts move the balance towards a more interactive style of information gathering for developers.
User documentation is generally written for a particular version of the software. It doesn't need to be updated as the software changes, because the user is insulated from that change. It needs to be updated when a new release is made. A developer, however, is working with the code as it is from minute to minute. The developer's situation can be made more like the user's by forbidding developers to work on the same piece of code and having internal releases (e.g., mediated by the source-code control system), but the pace of change is still much faster than it is for users, and the rarer you make internal releases the more painful integration becomes. Thus, developer documentation needs much more frequent updating than user documentation. This makes it more of a burden and a distraction for the developers who would have to write it. This, too, shifts the balance towards writing less.
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. With badly written code, this is a horrible option. With well-written code, it can be quite appealing. If the interface to a given part of code is defined by a file containing signatures (declarations, whatever you like to call them) for the functions in that interface and brief comments describing their contracts, then that file can be as usable a piece of documentation as anything separate would be. And it can't get out of step with the code, because it is the code. If it's wrong, the compiler will tell you. The availability of this other means of communication again shifts the balance away from written documentation.
User documentation can be written by technical writers. They know how to write documentation for users. Developer documentation, because it changes on a much shorter timescale and because it requires more intimate knowledge of the code, cannot so usefully be written by technical writers. It should be written by the people who write the code. But many people who write very good code write bad documentation. It may not be possible for developer documentation to be as clearly written as user documentation can be. This is another factor shifting the balance away from written documentation for developers.
Further to the last point: developers are slower at writing documentation than technical writers. They are also more expensive per unit time. Therefore, the cost of developer documentation is higher.
On to some other points. No one claimed that all documentation on all projects should be replaced with other things. If you think they did then you mistook brevity for precision. If you are working on a project with 200 developers then you will need more formal documentation than if you are working on a project with 6 developers. Obviously. This page is not useless just because its recommendations do not apply to all projects, and the right way to deal with that issue is to add a note saying "This will work less well for larger projects" or something, not to declare the whole thing useless just because the approach would need modifying if you were writing, say, Windows NT.
You mentioned the manpage for find. I think that's a poor example. find has about a million different command-line options and is notoriously difficult to work with. If a part of your software is like that, improving the software is as likely to help as documenting it. (This isn't, of course, always possible. Again: no one said all projects should eliminate all their documentation.)
One other thing about find. I'd actually find the code about as useful as the manpage, given a decent development environment and assuming the code is clearly written. So there.
So you say that finally some reasons. Well, it's not quite. I'm not responsible to put some reason in criticizing some ideas that have no proper justification, by guessing and filling in what the initial authors might have wanted to say but they didn't because they were lazy or because they were ignorant enough not to realize that what might have worked for them occasionally doesn't apply to software development in general and it is definitely harmful in a lot of situations. Not everybody is called upon to write patterns or proto-patterns or give advice to others. If you do that you better think twice and you'd better live up to the responsibility of giving good advice.
As you may still witness the page is not put in context and the affirmative idea (that it's useful or good to ReplaceDocumentation) is unsubstantiated. It is not put in the right context, it is not justified though it goes against everything that a lot of software professionals (including me ) have come to know about from years of experience as well as many books. This is a logical fallacy: you claim to revolutionize the world and you claim a revolutionary thing, than you say others can't refute your revolution, even if it unsubstantiated.
And going to more concrete things the manpage for find is a very good example, and I think if you bothered to check out what you were talking about, before you talked about, you wouldn't have picked it up for an argument. Please be so kind and explain to me how millions of options can fit in 23 man pages (on a 24 x 80 character screen) together with full explanations of what every little thing is supposed to do. It might be notoriously difficult to work with, maybe for beginners, newbies and wannabies, and even those must have the extra quality of being lazy enough not to read the man page and not to educate themselves in elementary shell scripting. The command is very precise, simple, useful and very well documented (in the man page of course). Be my guest and stare at several sources all day, because find.c alone won't give you enough clues, just to prove a stupid point about SelfDocumentingCode. The code in there is extremely well documented, it is written nicely, properly formatted, clear variable names and function names, still reading that code instead of reading the man page is completely and absolutely nuts. If you want to use the find command you read the man page, if you want to extend it, modify the code, write your own version, only then you have to read and understand the code.
The distinction between the interface and the implementation is absolutely a positive thing. There's no need to argue about that. The client of an interface (for the purpose of this example, the find command) does not need to read and understand the implementation, he only needs to know the syntactical form of the interface (in this case, the command line options; in other cases, a function declaration or a Java interface or whatever else is there), and to know the semantics of it which needs to be put down in the documentation (man page, help file, javadoc etc...). This is basic software engineering and it takes more than some unsubstantiated claims to prove that this is wrong (or wrong in some cases at least) and can be replaced with: OralTradition, EnlargeUserBase, SelfDocumentingCode, TrainUsersFirst or whatever else XP or anyone else might come up with (anybody care to clarify what finally happened with CccUserManual?). Those are the true AntiPatterns and not the well-established and substantiated practice of documenting both the interface to the end users (User manuals, help systems, etc, etc) and the interfaces for the developers.
At least until proven contrary. And the supposed proof has not even been sketched so far by the proponents of this page because they were lying lazy, waiting for me to come up with some arguments against their arguments so that they can prove that my arguments are wrong. I shall conclude that all the problems gathered so far in ProblemsWithDocumentation are in fact problems with unprofessional people. Both with those in charge of writing documentation and those who use some software product in order to do their job. None of them is a problem inherent to the nature of documentation, like, for example, I might have a gripe with Java because it loses typing information and it forces me to use the cast operator every other 10 lines of code - which is an example of a problem inherent to the nature of Java.
I'm getting fed up with this aggression, so I'll be brief.
I did not say that find is not well documented. I said that find is complicated; which it is. I have difficulty understanding how someone too literalistic to understand that "about a million" is hyperbole could also somehow happen to turn that into "millions", by the way. And I said that find could do with simplifying; it could. The large majority of uses of find use (between them) only a small fraction of its features. It could do with refactoring; all those tests it can do on a node it's visiting could be delegated to external programs. (In other words, all you really need is -exec plus appropriate tools for classifying files.) Probably better still, for reasons of efficiency, would be to build it into a programming language, so that those tests become function calls instead of program invocations. The way it handles -exec is a pain, because it neither interpolates "{}" when it occurs strictly inside an argument nor passes commands to a shell; this considerably reduces what you can readily do with it. Some implementations have had race conditions which lead to security holes. (That isn't a problem with the design of find per se, but I think it says something about its complexity.) Certainly, it's a useful tool, but it has plenty of suboptimalities; which is all I said.
Let's not start arguing on the sub-optimalities of find. It is a complex tool, but not as far as being notoriously difficult to work with. The largest part of its options are extremely easy to work with. Some of the more advanced features and the most complicated were actually developed by the guys who needed them. If you feel it needs refactoring, it is that easy: grab it and modify it.
What you did say and was incorrect was that you'd rather look at the source code instead of reading the man page, which is untenable. So you could do everything you like: refactor it, make the code better, but you cannot ReplaceDocumentation with something else than documentation, which is what this page is all about and which nobody has yet bothered to argument coherently.
So, would you be comfortable with a find command without man page, but only with clearly written code and a decent IDE? I don't think so. Let's just drop this dead argument and delete the whole discussion on find. We'd better concentrate on finding things that one can have a chance to use without documentation, or with a replacement for the documentation. Clearly written code is hardly a good replacement, or maybe you think differently but I'm waiting for good arguments.
I did not deny that the distinction between interface and implementation is a positive thing. You're wasting your time trying to convince me that it is, because I already agree. However, I think you are confusing "interface" with "documentation". It is possible to separate interface from implementation without separating interface from documentation.
Still no non-trivial interface that I know of is self-documenting, so you cannot ReplaceDocumentation. Documenting the interfaces, whether by comments in the source code (which are later fed to some tools to automatically generate documentation) or by separate html, man pages or whatever other form of documentation is the obvious and normal thing to do. Replacing that with whatever has been described here has been know to be an AntiPattern for a long time. Otherwise we'd have OralTradition instead of man pages, or God knows what else.
Let's take this proverb which is older than 2000 years old: verba volant, scripta manent. What do you think it says?
You are flattering yourself beyond measure if you imagine that the authors of the page were waiting for Costin Cozianu to come up with arguments against them.
Well, for who is waiting for? No argument is made for ReplaceDocumentation as yet. Nobody bothered to identify the contexts in which ReplaceDocumentation might stand a chance to work, and why. Who is expected to do all these?
The initial authors should have known at least that what their rants were, were against established and well-documented principles of software development. Therefore they ought to provide reasonable arguments, and they still do. Now whining that I allegedly interrupted their creation effort is not going to help. I only woke them up, maybe more abruptly than they'd have liked, maybe not in the constructive criticism kind of style that would flatter their ego.
Now, please either say something relevant and civil, or go away. Thank you.
Or I can invite you to make a decent positive argument in favor of ReplaceDocumentation. I explained clearly what is the logical fallacy of this page.
Do we want to argument about such basic things as to why documentation is good, and why one should strive for quality documentation, be it for the end-user, or just for one's fellow colleague who's using a documented interface to his software module? Well, if I had to do that I would rather not waste my time doing it.
Okay, I'm seeing two points here. First, that this page doesn't justify itself. Let's talk about that on ProblemsWithDocumentation. Second is that documentation simply can't be replaced... there's nothing better. I'll talk about that below.
I think it depends on the kind of documentation. Here's some thoughts. Please expand the list.
Don't do unto other what you do not want to do unto you
Before the brave XP coders here continue anymore along these lines (see TrainUsersFirst, EnlargeUserBase, SelfDocumentingCode) I strongly recommend/urge them to practice one of the following experiments:
The same comment applies as before. You are focusing on user documentation. The argument is about developer documentation.
The comments don't apply. All these examples are documentation for developers. End-users have nothing to do with them. They are written for developers in a specific style, that normal users would not be able to understand. They do document logical interfaces between distinct software modules that need to be put together in the process of software development so that an end-product for the end-users will be constructed.
The only argument in favor of classifying these examples as "user documentation" is that the software modules are written by a third party, and not directly by the team involved in a specific project. However this argument is superficial, the nature of modularization is what counts here. All those are software modules ready to be used and reused by developers in order to put together an end-product.
The third-party nature is absolutely crucial. If you prefer the term "third-party documentation" to "user documentation", fine. It makes little difference whether the users are developers or not.
If you still burn your brains on how to get rid of documentation problems, let me give you a little suggestion: hire a professional to deal with it. They are usually called technical writers, they do a very nice job, for which they are extremely well trained (or at least the couple of guys that I met).
You seem to be approaching this page from the point of view of external documentation. API documentation, user manuals, etc. I approached it from the point of view of internal documentation. Comments, design docs, etc. If I change the page to refer only to internal documentation, would that help? -- JimLittle
Depends what you mean by internal. For example, a QA team testing a large distributed system needs different documentation than the developers writing it. The internal marketing team needs different documentation from both the developers and the QA team. -- RobertDiFalco
I think this page could benefit from a list of the various kinds of documentation a project produces. Can you add the documentation you're talking about to the list above? -- JimLittle
I question whether the QA (QC?) team, development team, and marketing (advertising?) team need different information. In fact, the developers and testers should be working from the same information or their work is guaranteed to be in conflict. Shouldn't the advertisements for the product reflect what is being developed as well? (I am leaving the question as to whether written documentation is the best way to communicate this information unanswered. I am merely questioning the assertion that different groups need or should have different information.) -- WayneMack
People easily forgot what they have done. If you look at codes you haven't touched for 3 months, you would have forgotten the why and how. Documentation is used for more than communication between different people, it is also used to remind yourself what you have done! -- OliverChung
There's some disagreement about how this page should be categorized.
CategoryJoke | CategoryAntiPattern
or?
CategoryProtoPattern | CategoryProcessPrinciple
EditText of this page
(last edited December 4, 2005)
or FindPage with title or text search