(on Wednesday, 16 September 2009, 01:21 PM -0500):
> I think the main suggestions I can offer is to be more rigorous around
> the documentation set. Version the docs and maintain an archive of
> those versions. So there is a doc set for 1.7, 1.8, 1.9, etc. If
> someone is still using 1.7, they need to be able to look up things
> without having 1.8 ways of doing things creeping into view. Or vice
> versa.
The documentation *is* versioned, and you can download documentation for
any given release from the archives page:
http://framework.zend.com/download/archives
One initiative already underway is to offer versioned documentation on
the ZF site itself, however. We hope to do this for the 1.10 release,
but it requires a fair bit of site infrastucture for us to accomplish.
> And be rigorous about going through all the sections and updating as
> needed. So if I am looking at docs for 1.8, I shouldn't see 1.7 ways
> of auto-loading in the code examples of other sections. At least that
> is not what I would expect to see. I don't want to be overly critical,
> because I know documentation doesn't pay the bills, but I don't think
> it is unreasonable to make these suggestions on how to improve.
I don't disagree with you. But how do you propose doing so?
Zend_Application definitely changes the way we look at bootstrapping --
but I can assure you that, until it was brought up on this thread, it
never occurred to me that changes *elsewhere* in the manual were
necessary. What I'm trying to say is: how do we determine if changes in
a given component or a new component will require updates elsewhere in
the manual? Many component authors work on a single component, or
several related components, and have no idea how other components may
make use of them. While we on the Zend team try to mitigate such issues,
the fact of the matter is that with ZF the size it is, this is a pretty
difficult task.
So, my challenge to you is to come up with a workflow for doing so. :)
> The second item seems like it is already being addressed from the
> reply's of some others. I can only echo the need for more tutorials
> and better organization of those on the website. One difficulty I've
> had with ZF is that there are often multiple ways of doing the same
> thing. For example, there are probably (at least) three different ways
> of constructing a form (method chaining, array notation, creating the
> elements individually then attach them with addElements, vs addElement
> and then defining them via magic methods, etc, etc). Usually the docs
> only show one of those ways in detail, and are light on another way,
> and perhaps even omit entirely yet a third or forth way. I don't think
> the standard documentation is necessarily the best place to show every
> possibility, because useability starts to get impacted with the growth
> of details. Maybe this is where tutorials come in. Related to that,
> often times I've struggled with identifying the pros and cons of the
> different ways of accomplishing the same task. The docs tend to omit
> this type of distinction, and it would be useful in many cases to have
> this provided.
Some of these distinctions are difficult to determine until the
component has adoption. For instance, one method of use may be more
performant than another, but until a number of developers have used and
benchmarked each method, we cannot know.
As for documenting all use cases: this is a known problem, and one I'm
having difficulty coming up with a solution for. One issue is that we
build ZF to be extensible and flexible -- but those qualities often make
it very difficult to document.
Our plan for the "Learning Zend Framework" section of the manual is to
showcase what we on the team (or contributors) feel are best practices
for a variety of components, particularly when architecting a
full-featured website. I'm pretty confident that it will answer many of
the questions and concerns you and others have raised, but it's only a
start; we also need to examine the reference guide and make sure it also
gives a consistent message.
> -----Original Message-----
> From: Franck Delage [mailto:zf@web82.org]
> Sent: Wednesday, September 16, 2009 7:59 AM
> To: fw-mvc@lists.zend.com
> Subject: Re: [fw-mvc] so complex!
>
> Just to answer to Matthew :
>
> Matthew Weier O'Phinney a écrit :
> | First, we do make a number of assumptions: (1) you understand PHP, (2)
> | you know how to setup a web server, and (3) you have used and written
> | PHP classes. Are these inappropriate assumptions? I'd like to think
> | not; how can you accurately judge the benefits a framework provides
> | you unless you have a baseline to compare against?
>
> Of course these are not inappropriate assumptions.
>
> A framework is not one of those "softwares" which theorically allows you to build a wonderful website in 10 clicks. It's a tool, and a tool needs a worker.
>
> You can buy the latest beautiful Facom screwdriver, if you don't know in which direction you unscrew...
>
> M, thank you for your work.
>
> --
> Franck Delage
> Création et hébergements de sites web
> www.web82.net
>
--
Matthew Weier O'Phinney
Project Lead | matthew@zend.com
Zend Framework | http://framework.zend.com/
没有评论:
发表评论