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