Hello, i am new to cook, so far I love what I see.

However i am trying to follow the tutorial, there seems to be huge gaps in knowledge instruction.

For example page 4 of composition section goes immediately to things like
Layouts
- specify column sorting ...Change controls
Tables
- Define integrity constraints... etc

how do you do all these things?

some i figured out, but many don't have a clue what they are asking? like complete jdom, embed jquery framework, todo:yes.

am i missing some other documentation?

Im impressed you got that far. So far im liking this product but the documentation is virtualy incomprihensible. The "tutorial" is a complete waste of time IMO.

Sorry if i offend anyone, I appreciate the effort that was taken to prepare it, but frankly its useless as a learning aid. Which is a shame as I think this tool has huge potential.

As Admin has said many times, it takes so much time developping the new version of cook that there's less time to prepare doc. If we can help directly, we do. As for real proper documentation, it will come.

Dont get me wrong. So far I love this thing. And as someone with almost 30 years experience in SW development as a developer AND a documentation writer (never at the same time) - I know how hard it is for developers to write documentation - Time is just an excuse - the real issue is our brains arn't wired to write it after you have already coded, tested and debugged it. The LAST thing you want to do is write about it.

We (developers) are also usualy wired to think in terms of "function" - so developer docs usualy are full of explanations of "What" this is, or "what this feature does". But users usually need "How" to do things and most importantly "Why" you should do things. (critical when starting a learning process.)

I personally think the docs are terrible (as a user who is trying to learn how to use this tool) I also appreciate how much effort somebody went to to make them (as a writer) - as I said - I dont want to insult the effort that someone went to. I hope better documentation comes along. Who knows, once I get my head round some of the basics of this thing I may even have a crack at some myself.

Ive only been here a day and already im the most excited by the the potential of this thing as I have been about anything in the Joomlaverse for a long time.

For my part, i have two backgrounds : i'm primary a teacher, and then i became a dev. So i can relate to what you say.
And yes, it doesn't take long to get how cook can save you an huge amount of time

Yes, you are absolutly right, it is both a matter of time, but also a mater of "How can I switch my brain to present it ?"

Very interresting stuff you say What, Why, How ?
When I will really start to write the doc I have to choose a good presentation, and a good system.
Probably wiki, even if I am not absolutly convinced about wiki. What is your opinion about it ?

I would prefer to have a pure simple page, and effective. Articles with user comments, such as php.net

Now my head is up to the water (more or less), and I hope it will come during this summer.

In My opinion Wiki's are the devils work. I just dont like them at all for documentation.

I think the biggest problem with the current tutorial is that there is no clear goal. Its simply "Do this", Then "This", and then "this" and put this code here... At no time did I understand "why" i needed to write all this code in a tool that is supposed to build my component for me. There is a language issue as well, it hasnt translated that well from French (Who ever did it speaks far better french than I can - but its still feels "clunky") and is why, for me, I got so lost I simply gave up trying to follow it.

I would structure the documentation around a "project" (as it is) but i would first explain What Cook can do, and cant do, in terms of the finished component and explain why there must be some manual modification to the code. Then guide the user through the steps explaining "WHY" each step is required before showing "HOW" to do it. At the moment only the "HOW" is there.

I think having the zip files is a great idea - BUT - evn they were out of sync as things had been done in the sample files that wernt in the documentation. Which made me think id missed a step or done something wrong and again left me feeling more confused and lost.

Of course - once I have finished building my component - I will spend about 10 minutes on the documentation and it will be perfect

Very good inputs. Thanks.

K++

Do you know a good component or a web application that can organise this documentation in a easy way, and a bit of collaborative such as comments ?

Hi Admin.

No unfortunatly I dont. Other than using Joomla articles with some form of commenting system.

This is actually the issue I have myself with another project we are working on. I curently have set up a simple categogory based set of documentation articles in joomla to create the documentation (but havnt had time to write it yet! lol... the old "no time" excuse!) I hadnt planned on any form of collaboration or commenting but that is a good point. I'll have a think about it and let you know how my experiments go. It probably wont be for a while though sadly - we are up to our necks in work for clients at the moment.

ALSO: dont forget video. The video tutorials you have done are great. Very clear, and well presented. I know they take a little longer to prepare but lots of people learn faster by being "shown" that by reading and trying.

Essentee