[Dojo-interest] Dojo Documentation: A Proposal
russell.jones at cas.ox.ac.uk
Wed Dec 5 15:11:17 UTC 2007
In turn I disagree with you. Boot-strapping is essential. There should
not be a requirement for priests to induct novices into the mysteries of
dojo or anything else.
Jon Sykes wrote:
> I'm no doc writer, but I am a consumer of docs, and I have to disagree
> with most of what you say below.
> That said, this is an open source project, so if you want to
> contribute situational documentation, that's your choice and it will
> be an awesome addition to the docs.
> On Dec 4, 2007, at 4:31 PM, Daniel wrote:
>> Jon Sykes wrote:
>>> I'd rather have the time spent on core basic API description docs
>>> first and then add situational docs later.
>> This is a classical error among inexperienced doc writers. The fact is
>> that API reference is completely useless if you can't even get
>> Look at all the problems I've had.
>> Example 1:
>> Dan> I can't get my application to work. I don't know where to start.
>> ...> Did you include dojo.addOnLoad() ?
>> Dan> No.
>> ...> If you had searched for doo.addOnLoad() you would have found it.
>> Dan> How am I supposed to know that that's what I need?
>> Example 2:
>> Dan> I can't get this to work.
>> ...> You should have used dijit.byId(). If you had searched for that
>> would have found it.
>> Dan> How am I supposed to know to use that function?
>> These things should not have happened. These are "hello world" kind of
>> programs. An experienced programmer should not get stuck trying to
>> program "hello world".
>> The problem, Jon, is that an API reference is only really useful to
>> people who already know how the system work. Why should you expect a
>> user to search for function Foo() if there is no reason to expect
>> him to
>> dream up the name Foo() on his own? Or to know that the function Bar()
>> won't work without Foo()?
>> Do you have any idea how frustrated I get when somebody says that I
>> should have searched for a particular function name when the whole
>> problem is that there is no way for me to find out what the function
>> name is? It's circular. It's self-defeating. It's crazy. You can only
>> learn how to do XYZ if you already know how to do XYZ. Don't you see a
>> problem with that? Several times already have list members told me I
>> should have looked at something that I could not possibly know
>> Task oriented help is *critical*. At a minimum, you must have enough
>> documentation to let the user get started with basic tasks, and right
>> now Dojo doesn't even have that. And no, those tutorials don't do it.
>> For example, they say nothing about how to make a functioning program.
>> In fact, API reference is less important because it can be partially
>> supplanted by examples. And if you can get past the initial hurdle of
>> writing a simple program you are better able to get something useful
>> of examples or the auto-generated API reference.
>> FAQ: http://dojotoolkit.org/support/faq
>> Book: http://dojotoolkit.org/docs/book
>> Forums: http://dojotoolkit.org/forum
>> Dojo-interest at dojotoolkit.org
> FAQ: http://dojotoolkit.org/support/faq
> Book: http://dojotoolkit.org/docs/book
> Forums: http://dojotoolkit.org/forum
> Dojo-interest at dojotoolkit.org
More information about the Dojo-interest