On Jan 5, 2007, at 9:27 AM, Veloz wrote:
I am a relative new-comer to Cake and am impressed and appreciative of
the quality of effort that has gone into the project so far.
However, I have found that many of my questions are not answered in
"The Manual" nor in Tutorials/FAQ's, nor in the Google Group, etc.
Ths is especially true for changes that are part of the newest
releases.
So I have turned to the code to get the "answers".
What I have found is that the code is nice and clean, all pretty and
with well named variables, etc, so kudos to the team for that.
But to my disappointment the code is effectively undocumented too,
leaving me in a bad position: I either have to tell my boss that I
made
a mistake and Cake is not the tool for us, or I have to spend more
days
trying to figure out someone else's code and add this to my project
timeline.
My newest case in point is the FormHelper class, which presumably one
needs (as of release 1.2xxx) to emit form input tags.
The first developer release for 1.2 was released on Christmas. I
imagine I could have done a better job preemptively documenting new
things in 1.2, but don't be too hard on me for not documenting
features that aren't even final yet.
Its hard enough for me to document exist final features. I don't
think we'll try to nail down something that is still a moving target,
thus the "development" label on the release.
<snip>
So, my suggestions for improving the state of documentation for Cake
is:
1. Do not release any version of Cake unless The Manual has been
updated to reflect the changes in that release.
I don't think this is always practical, and in some cases,
development releases allow us to see how things work in the wild.
Seeing the community response helps us know when to modify things,
either because of bugs or requested features or whatever.
I agree with you, however, if this is referring to final releases (as
all our releases are stable :).
2. Make sure all functions are commented before allowing the code
to go
into a release. This should be part of your "conventions", not just a
"nice to have".
Again, this just isn't practical for development releases, due to the
nature of them not being a final release. It's kinda like writing a
review on a broadway play's dress rehearsal.
As with many other open source and free efforts, its always better to
volunteer to fix the solution rather than just point out where things
need to improve. A negative budget and many other priorities often
make it hard to decide where to best place our efforts. We totally
agree with what you're saying here, but your point would have more
impact on the community if you jumped in and made an effort to
contribute and fix the problem.
Anyone is welcome to supply some documentation to the code blocks -
please just log a ticket at trac.cakephp.org and attach a few lines
you think might clarify the situation. Having everyone help out makes
fixing these issues much faster for us - especially if you've already
spent the time figuring a section of code out.
Thanks,
-- John
CakePHP Docs
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups "Cake
PHP" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/cake-php?hl=en
-~----------~----~----~----~------~----~------~--~---
