[Dojo-interest] Dojo Documentation: A Proposal

[Russell Jones]

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.

Russell Jones

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  
>> started.
>> 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  
>> you
>> 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  
>> existed.
>>
>>
>> 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  
>> out
>> of examples or the auto-generated API reference.
>>
>> Daniel.
>> _______________________________________________
>> FAQ: http://dojotoolkit.org/support/faq
>> Book: http://dojotoolkit.org/docs/book
>> Forums: http://dojotoolkit.org/forum
>> Dojo-interest at dojotoolkit.org
>> http://dojotoolkit.org/mailman/listinfo/dojo-interest
>>     
>
> _______________________________________________
> FAQ: http://dojotoolkit.org/support/faq
> Book: http://dojotoolkit.org/docs/book
> Forums: http://dojotoolkit.org/forum
> Dojo-interest at dojotoolkit.org
> http://dojotoolkit.org/mailman/listinfo/dojo-interest
>