If It Isn't Documented, It Doesn't Exist

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?

also, this seems relevant. It’s documented, but you aren’t expected to understand it. Does it exist? :wink:

a href="http://www.google.com/codesearch?hl=enq=+file:/usr/sys/ken/slp.c+%22You+are+not+expected+to+understand+this.%22+show:Ljj4gw8sDcU:LpqPd8QofXc:rZ61TsK1o2osa=Ncd=1ct=rccs_p=<a href=“http://pdos.csail.mit.edu/6.828/2003/6828sw.tar.gzcs_f=6.828/v6/usr/sys/ken/slp.c#a0"http://www.google.com/codesearch?hl=enq=+file:/usr/sys/ken/slp.c+%22You+are+not+expected+to+understand+this.%22+show:Ljj4gw8sDcU:LpqPd8QofXc:rZ61TsK1o2osa=Ncd=1ct=rccs_p=http://pdos.csail.mit.edu/6.828/2003/6828sw.tar.gzcs_f=6.828/v6/usr/sys/ken/slp.c#a0/a”>http://pdos.csail.mit.edu/6.828/2003/6828sw.tar.gzcs_f=6.828/v6/usr/sys/ken/slp.c#a0"http://www.google.com/codesearch?hl=enq=+file:/usr/sys/ken/slp.c+%22You+are+not+expected+to+understand+this.%22+show:Ljj4gw8sDcU:LpqPd8QofXc:rZ61TsK1o2osa=Ncd=1ct=rccs_p=http://pdos.csail.mit.edu/6.828/2003/6828sw.tar.gzcs_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.

(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 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

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 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.

“… the number one reason why some JavaScript libraries fail.”

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

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?