Nicholas Zakas enumerates the number one reason why good JavaScript libraries fail:
This is a companion discussion topic for the original blog entry at: http://www.codinghorror.com/blog/2007/01/if-it-isnt-documented-it-doesnt-exist.html
This is a companion discussion topic for the original blog entry at: http://www.codinghorror.com/blog/2007/01/if-it-isnt-documented-it-doesnt-exist.html
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.
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.
How about DDD - Document Driven Development. Write the documentation for a program before starting to code it. :-p
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…
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.
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.
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.
“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…