I can't agree more. I maintain my company's login script and have had to learn to use VBScript to do so. If it weren't for lots of documentation, some by Microsoft, and a whole lot more by 3rd parties, I'm not so sure that I would have been able to learn it. I am self-taught, and my previous programming experience was on an Atari 400 (which doesn't count), so I would be dead in the water without documentation.

ahh documentation, I am actually writing one now, and I cant seem to find any good examples on how its done. I have ofcause written documentation before, but like with programming examples it is always nice to learn something from other people.

So yes alot of bad / missing documentation out there, but at least one part of the products you can look into the open code, the other part, well you have to pay or pray.

I think the worst part documentation, is all the stuff that you never read, like 50 pages of introduction, 50 pages about the book you are reading, 10 pages before and after each chapter about what it is written about, and so on.

Like this stupid printer manual, 10 illustrations on how to open the box and put in 2 cables that can not be inserted in any different way. But the printer dosent work, so you look into the manual, .. "did you remember to plugin in your cable? " What a f#"#k retart do they think the customers are? Or maybe you want to update the printer, and you only get like 3 lines of text description.

If 99% people tend to have problems with putting cables from a printer to pc then god help us, I wonder how they recharge their cell phone.

If the products has no documentation then I think they have saved that to do something else to improve the product or was too non-sales-minded. But if the products comes with tons of documentation that makes the bible look like a postcard, but with no usable content, where you have to call support to get some supporter who ask if you have plugged the cable in...

Yes good documentation is hard to find. Just wish people would document all and not brag about all the easy stuff.

It would be good if they had a link to their documentation on their front page though, it might be less helpful if it isn't easy to find...

Documentation is a full-time job in itself. So little time is planned for documentation that it's often pushed aside in favour of "getting something that works", which is a shame. Help files and end-user documentation in general appears to be thin on the ground in most cases I've seen.

"If it isn't documented, it doesn't exist."

I think another quip about documentation is, "If you can't explain it, you don't understand it." Lack of writing and communication skills is prevalent with many programmers, as evidenced by the APIs I try to use. I have to experiment far too much to figure out how some things work, and when that is the case, it's harder for me to trust what it is I'm using.

If I get a faculty position after my degree, I'm going to push for a writing requirement in the computer science program.

"Good documentation is hard to find. Particularly on open source projects."

Truer words have never been spoken.

I've recently begun to use OpenCV in a computer vision product at work. Prior to this we were using some propietary libraries that had admittedly poor documentation but I've noticed that OpenCV is absolutely horrendous. The function calls make assumptions about the parameters passed that you won't find out about with reading the source (sometimes not then either) or you get a wonderfully cryptic runtime error message. I've yet to find a single tutorial that adequately explained how to use some standard techniques like the fourier transform.

I have always been of the belief that bad code with good documentation is infinitly better than good code with bad (or no) documentation.

We've used the 'If it isn't documented it doesn't exist' line many times and I find its more true within a company. Undocumented libraries will still occasionally be demystified by curious hacking types however within a company there is rarely the opportunity to outlay the time required for such exploratory work.

I've been inspired to write some further discussion of documentation - in particular how it pertains to Javascript libraries such as YUI on my own blog (http://blog.wioota.com/2007/01/24/javascript-barriers-to-rapid-development/).

Jeff, great content as always...

It's unfortunate that so many of the projects out there suffer from lack of documentation. I'm often pulled into a project half-way, and it's very difficult to get up to speed when you're told to go look at the code as a means of learning the system. What if it's buggy? Oh, well, um, we, ahh, er...

Yeah. Exactly.

In VS2005 (in C#), if you type "///" the editor will automatically outline an XML template for the documentation to be inserted into the manifest. If you ever use the reference browser, this is what you are reading.

To clarify, if you just fill in the descriptions, etc, you will not NEED documentation, as it will automatically be added to your output files (in the manifest).

I feel this way about FxCop. The reason no one writes custom rules for it is no one knows how, and there's no good way to learn that doesn't involve a greater time investment than anyone can afford.

Perhaps the lack of really good documentation is a function of a general degradation of sound practices over the years. Does anyone flowchart anymore?

The main reason Javascript libraries fail (we need to define "fail" here , does it mean "I don't use it so it 'failed'" or "no one uses it") is LACK OF USEFUL FUNCTIONALITY.

Prototype, one of the most used JS libraries has practically NO documentation except for a few "AJAX-ify your web site" articles. Dojo, one of the most fully fleshed out libraries (I'd say, over-engineered) has documentation that is very sparse. Requiring you you "reverse engineer" examples.

The main reason Javascript libraries fail, imo, is a lack of useful functionality combined with a lack of compelling examples. Which basically boils down to....marketing.

re: open source doesn't provide documentation. I don't think that closed source is any better. If you look at the big dogs in both closed source (Microsoft's .NET and Win32, Apple's Cocoa and Carbon) and open source (Linux, Apache) you'll find excellent documentation of the public APIs. Once you move away from the resource-plentiful big dogs, the documentation curve drops off severely. Does that nifty ASP.NET component you are paying $500/year for have autogenerated CHM files with a few token comments or does it have a "your component unleashed" book by APress?

What's been working for me lately is writing the documentation for individual components (classes, methods, etc. - not the whole product obviously) before coding them.

It sounds very non-agile, I'm sure, but it's actually cut down substantially on the need for head-scratching and refactoring, because the most common reason for that is not remembering what something does or how it's supposed to work or be used, and writing the doc in advance forces me to answer those questions in advance.

Helps avoid feature creep too - if it can't be properly explained, it probably doesn't belong in the product.

also, this seems relevant. It's documented, but you aren't expected to understand it. Does it exist? ;)

<a href="http://www.google.com/codesearch?hl=en&q=+file:/usr/sys/ken/slp.c+%22You+are+not+expected+to+understand+this.%22+show:Ljj4gw8sDcU:LpqPd8QofXc:rZ61TsK1o2o&sa=N&cd=1&ct=rc&cs_p=http://pdos.csail.mit.edu/6.828/2003/6828sw.tar.gz&cs_f=6.828/v6/usr/sys/ken/slp.c#a0">http://www.google.com/codesearch?hl=en&q=+file:/usr/sys/ken/slp.c+%22You+are+not+expected+to+understand+this.%22+show:Ljj4gw8sDcU:LpqPd8QofXc:rZ61TsK1o2o&sa=N&cd=1&ct=rc&cs_p=http://pdos.csail.mit.edu/6.828/2003/6828sw.tar.gz&cs_f=6.828/v6/usr/sys/ken/slp.c#a0</a>;

@Allied -
Great tip, thanks!!

I'm currently working on the documentation for my first commercial C# project. I try to write the documentation as I go, sort of taking turns writing tests, adding features, debugging, and sporadically writing documentation. As the sole developer it can seem like a waste of time to document things more than sparsely, but reading articles like this really helps motivate me. If I don't develop good habits now, I probably never will. I can improve the efficiency and elegance of my code over time, but the only way to learn to document my code is to do it.

Very good post. I've run across this so often in some major ways. For instance, the Infragistics controls have terrible documentation. The only saving grace is their forums. I wonder if forums can count as documentation though?

Could not agree more. I even very strongly believe that documentation should come *before* coding. It then improves tests, APIs and design in general. To put a tweak on what someone said earlier: "If you can't explain it convincingly, you don't fully understand the actual use case yet."

http://peomeint.blogspot.com/2006/08/beyond-tdd-documentation-driven.html

I have written also written an open-source tool, JCite, that allows you to cite test code right into the docs, so you can guarantee your examples are truly correct, and an article exploring the issue in greater depth.

http://arrenbrecht.ch/jcite/index.htm
http://arrenbrecht.ch/articles/SourceCiting.htm

All this is, by the way, much in line with what leading API designers in Java (Josh Bloch) and .NET (Krysztof Cwalina) are saying.

I have noticed more times than not when I am working, and even when I write the code, I many times forget how something works unless I comment it. I have actually gotten myself and the fellow developers in the office to at the beginning of every stored procedure put an execute statement at the begining of the parameters and comment it out, so that you always have a way to test VALID data to kinda trace your way through it. I love open source for work, because I would rather NOT code it myself, if there is something i can knock off, I would rather do that, and I believe that is a reason why there is lack of documentaion... people like me wanting it, so they try and keep you away by not 'splainin them selves.

Full Disclosure: I now work at Yahoo (on Upcoming.org), and I use their library that I'm about to discuss.

Pre-Yahoo, we used to use prototype, but during the middle of last year, the Yahoo UI Library (http://developer.yahoo.com/yui/) came into full strength for us, and we switched. We now use it extensively around Upcoming.org for quite a few things, and one of its primary strengths is great documentation. It's got a fully funded staff that answers questions on its mailing list, and it's got several full time engineers improving it daily. Now, let's talk about their documentation.

In addition to official code examples (http://developer.yahoo.com/yui/examples/connection/index.html), they have autogenerated API docs and overview pages (http://developer.yahoo.com/yui/connection/) with Getting Started sections and more. Not only that, but they have an entire Javascript Developer Center (http://developer.yahoo.com/javascript/) dedicated to general Javascript concepts and usage of their products.

I don't work for them, but they're one of the best platforms at Yahoo, and for the purposes of this post, they definitely deserve a mention for their extreme documentation.

(68 projects in the Solution) + (234 tables in the *main* database) + (7 levels of inheritance) + (0 Documentation) = I start my new job a week from Monday.

Some random thoughts ...

IBM products used to come with two manuals. The "User's Guide" had many examples in context, showing how users most often do things. The "Reference Guide" specfied the effect of every single option and was essential when you wanted to leave the beaten path.

My text editor of choice is KEDIT, spawn of IBM's mainframe XEDIT. The manual for KEDIT are shining examples of clarity and dis-ambiguation. Thanks, Kevin!

I like Java code to explain itself well enough comments and documentation on the low level stuff is not necessary. But I like to put user and reference level documentation in the package level JavaDoc.

Trying to think of other examples of good doc ... I think I picked up what I needed to use Lucene from one or two examples, then found the details on all the options with ease.

Scott: You would have been more correct about 6 days ago. http://prototypejs.org/api

My take, I like good documentation. I hate bad documentation. It seems like there is a lot more of the latter.

I currently contract for a fairly large company, and they produce voluminous amounts of bad and non-used documentation. I think good documentation comes in small doses and tends to be practical / examples more than specifications.

I used a lot of 'I' in there, because this is my opinion and is so poorly researched it would blow your mind.

I agree with your example - URLRewriting.net has excellent documentation.

> if you just fill in the descriptions, etc, you will not NEED documentation, as it will automatically be added to your output files (in the manifest).

IMO, creating ONLY ref documentation is far from sufficient. I maintain that you can't learn a new product from an API reference. I don't think I'm unusual in this opinion -- people read books and articles all the time to get a handle on some technology, and these days, one of the most popular types of documentation on our site is videos.

Ron Jacobs interviewed Scott Hanselman on his ARCast show, where Scott talked about "All non-software artifacts should approach zero" (links below). Scott pointed out that documentation often becomes out of sync with the actual code/application behavior. However, I see this being in direct conflict with Jeff's position. Or can documentation become a 'software artifact'?

http://www.skyscrapr.net/blogs/arcasts/archive/2006/12/21/595.aspx
http://www.hanselman.com/blog/ARCastnetInterviewedByRonJacobsAtTechEd2006.aspx

I want to come work for you. I actually work for a CIO who does NOT like documentation :(

I couldnt agree more!

I recently wrote an article concerning the troubling habbit of skipping over documentation when using the Agile development method.

<a href="http://noodlejunkie.com/articles/2007/01/23/the-false-dilemma-of-agile-development" title="noodlejunkie.com">The false dilemma of agile development</a>

Yes, yes, yes!

Man am I tired of downloading tools and components that don't have documentation where you spend a half an hour just to get the thing to work.

I build a lot of tools and components and one of the first things I usually do is set up the documentation for them at the start. Not only does that help other developers use the product later on but it also makes my job easier when I need to figure what the method did exactly <s>...

Some people also seem to feel that Unit tests take the place of documentation or examples. No freaking way... take the samples out of your tests and write them up and explain them as well...

Key too is having tools that work for you. I have tools that I built for documentation for myself (and also sell), but everybody's different and comfortable with different things. BUt integration into the process is very important. Doing docs after the fact will rarely provide quality results.

I just looked at the UrlRewritingNet documentation and I have to say I'm underwhelmed. Under the heading "Why rewriting (sic) my Urls?" there is the following:

> If your blog is ready and online you want to be found by potential readers on search engines like Google or Yahoo. These search engines send bots out to the World Wide Web to find interesting content. So what do you mean what the bot does with a Url like shown above? Not much, right.

Err, pardon? I can't even parse that second-to-last sentence.

Moreover, if I understand it correctly, the entire stated benefit of URL rewriting is that it helps your site to be parsed by *search engines*. This is entirely unsubstantiated - why should the search engine care whether or not the URL contains some idea of the topic being discussed? If the authors have any basis to the claim that search engines "could find the topic of the blog entry in the Url", they haven't shown it. Look, I'm all for cool URLs, but the payoff is generally for human readers.

This is on the first page, and they already lost me. The benefit of the tool is not stated clearly.

No disrespect to the UrlRewritingNet developers: I'm sure the documentation is better than most open source libraries. But there surely must be other projects you could point to as an example of great documentation. Projects whose documentation includes grammatically correct English and states the intent of the project clearly, for example.

One thing I have grown to dislike is when people rely solely on community documentation.
Don't get me wrong, community documentation is great and very useful. However, when I'm just learning something I really appreciate being able to read through something all in the same style (both the pros and the code). I have my own coding style, and I'm not just going to copy someone else's, but styles differ even within API's and having to flick back and forth between different styles with an API you are unfamiliar with is just confusing.
It always scares me when an API doesn't even have examples. It's as if the creators can't even think of any uses for it themselves.

@RickM: I don't think Jeff and Scott are necessarily in disagreement, just talking about different types of projects.

If you're building a library for other developers to use, the "Product" is a combination of the code and documentation. Thus for each release of the product, you'd have an equivalent and up to date release of the documentation.

Contrast that to an internal business application which is constantly being "released" and updated. It doesn't necessarily make much business sense to continually update the documentation in parallel with the code, especially when the people still working on the code are still in the building.

How about DDD - Document Driven Development. Write the documentation for a program before starting to code it. :-p

To play devil's advocate here (in the context of software libraries which is where this discussion seems mostly aimed) - why write documentation, since nobody ever reads it? For most developers, intellisense is the documentation. If they can't get something working they will either give up, look for sample code (either on the net, or samples which you've provided them). To paraphrase the Framework Design Guidelines - your APIs should follow common idioms and be "self describing" - able to be understood without any external materials.

I was going to do some useful work this afternoon, but all the life got sucked out of me when I read an email from the boss that we were going to have a meeting tomorrow morning about all the problems we are having with radios. I have been trying to understand what is going on with the boss for a while now. Mostly I can just avoid him, which works pretty well. But then this happens and I wonder if maybe he is some kind of vampire demon from hell. So you can argue about the merits of good documentation versus good or bad code, but if you do not care, it does not matter. Someone stake me and put me out of my misery.

I agree with you 100%... one javascript library that i just loved for being well documented is the simple calendar widget, It clearly states the purpose of every variable and method, if provides examples of how to change them to get different results.
Can be found here: http://www.garrett.nildram.co.uk/calendar/scw.htm

The first thing I thought of when I read "documented" and "Javascript library" was Yahoo's Javascript UI library ( http://developer.yahoo.com/yui/ ). I personally found it a joy to work with -- the cheat sheet pages and the numerous official examples were more than enough to get me up and running in very short order (even though I'd never used a JS library before). Sure, it's not a full-fledged book, and it admittedly has its typos and out-of-date portions, but you roll with the punches on ever-evolving release-often OSS, and overall it seemed like fantastic stuff to me.

Ship your tests with your API. Unit tests are a great way of providing how-to documentation, and they are self-correcting when they get out of sync with the API. This may not be complete (tests may explain how, but not WHY), but it is a heck of a start.

Ultimately, it just comes down to meeting the needs of your customer. Identify your customer, work with them to figure out what they need, and provide it. If that need includes documentation, then so be it.

I wonder where Hanselman got the "non-software artifacts ..." line. Hmmm ...

".. the number one reason why *some* JavaScript libraries fail."

Fixed. jQuery, Prototype and YUI all have relatively good docs.

The most important part of the documentation is making it clear what part of it is NOT important for the pressing task at hand. (Perpendicularity.) The user is not going to cuddle up with your manual.

BTW, this is the point where many give up on the idea of writing docs altogether. "He's going to skim though it, and I'm supposed to play Hemingway?".

Another scourge is the desperate perceived need to sound scientific. Not giving examples; or describing simple things in Backus-Naur form (WTF?). The trouble is that some parts of your project really are lame; explained in plain language would expose them as such. It takes actual courage.

Scott Mitchell: Isn't "Documentation-Driven Development" pretty much what Knuth's "literate programming" does? (Admittedly, it's pretty low-level documentation, usually, since it's mostly documentation of the algorithms. But the interfaces get documented too, if you do it right.)

That does make a lot of sense, though, as a serious idea. It's just one step past test-driven development; you don't know what tests to write until you know what the code should be doing, and documentation is a good workable way to work out whether that's sensible or not and to get it into a concrete form.

And what if I spend two years making some project. I decide to give it available as an open source but don't care if there is someone who wants to use it at all. Do I really have to sit and write documentation, which I don't need as I understand my project well, for months just for someone else who would like to come and have my hard work ready for nothing in the moment?

@Oldes:

If you don't want anyone to use it, then no, you don't have to write any documentation. But if you don't want anyone to use, why are you bothering to release it at all?

I agree with "I have noticed more times than not when I am working, and even when I write the code, I many times forget how something works unless I comment it", so I have to write comment within code lines so that I can know what they means when I read the program.
Liwen

I read the python language documentation, it seems it is bad, all the functions only have pure literal explanation but donot have a single example,
so I feel very hard to understand what is the use of a simple function.
Liwen