Starting the 3.0 branch

classic Classic list List threaded Threaded
93 messages Options
12345
Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

Marco Pivetta
On 19 June 2013 09:56, Marc Tempelmeier <[hidden email]> wrote:

Hi,

 

the problem right there I see every day in my company. They simply don´t want to search good examples.

The second argument against that is, how do you know if that are good examples in the first place?

You can spot that, beginners don´t!

In many companies they people don´t have time to educate themselfs much. They have to have a good

Documentation with _good_ examples.

I don´t get why everyone here is refering to other places or their blogs for that. They is _no reson_ to

Prefer multiple blogs etc. over examples on the official site.

 

Just my multiple cents on this

 

Greetings

 

Marc


Just a quick note to remember to everyone here that every coder who replied to this discussion is OBVIOUSLY an enterprise application top-notch level OOP coder/expert with strong application design patterns understanding from reading php.net.

The framework is a tool. If you (reading this) learned how to use a screwdriver from a manual I'd like to meet you and I want an autograph from you, because you're unique.

</rant>
Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

Marco Pivetta
In reply to this post by Marc Tempelmeier
My excuses to Marc for sounding harsh and directly pointing at him.
The reply wasn't against him nor against anyone, it was a rant that came up after I've kept back from replying to this thread (and the zf2 acceptance ratio one) for a long time.

The problem about all "those developers" is simply described here: http://www.troyhunt.com/2013/02/the-ghost-who-codes-how-anonymity-is.html

For 3.x, I'm going to start working on zend/servicemanager for ZF3 in 2 weeks (as a branch, not necessarily accepted in ZF, but we'll see)


On 19 June 2013 09:56, Marc Tempelmeier <[hidden email]> wrote:

Hi,

 

the problem right there I see every day in my company. They simply don´t want to search good examples.

The second argument against that is, how do you know if that are good examples in the first place?

You can spot that, beginners don´t!

In many companies they people don´t have time to educate themselfs much. They have to have a good

Documentation with _good_ examples.

I don´t get why everyone here is refering to other places or their blogs for that. They is _no reson_ to

Prefer multiple blogs etc. over examples on the official site.

 

Just my multiple cents on this

 

Greetings

 

Marc

Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

EvanDotPro
In reply to this post by Marc Tempelmeier


On Wed, Jun 19, 2013 at 12:56 AM, Marc Tempelmeier <[hidden email]> wrote:

Hi,

 

the problem right there I see every day in my company. They simply don´t want to search good examples.

The second argument against that is, how do you know if that are good examples in the first place?

You can spot that, beginners don´t!


This is a very general problem in software development -- it's precisely why I tell most smaller clients to always make sure they have at least one senior developer on staff to supplement their junior developers. If a company thinks they are saving money by employing all junior developers, they'll quickly learn that it's not the case; likely on their second or third re-write. I see it all the time -- in fact, it's usually why companies end up coming to me in the first place. If you can't afford a full time senior developer, you've pointed out a perfect example of why you should at minimum contract one as an advisor to help with these sort of things. This is getting off topic, but the problem you just described is something I see all too often, and it's a problem that's easily avoidable.
 

In many companies they people don´t have time to educate themselfs much. They have to have a good

Documentation with _good_ examples.

I don´t get why everyone here is refering to other places or their blogs for that. They is _no reson_ to

Prefer multiple blogs etc. over examples on the official site.


First of all, a good subscription list of blogs is imperative to following any topic you're trying to keep up with, technical or otherwise. If you're trying to be a ZF2 developer and not following at least a few blogs, I'd argue you're not doing your part to help yourself, your company, and your project succeed. Anyone who hasn't should get their RSS readers out and start subscribing: http://framework.zend.com/participate/blogs

Keep in mind that a lot of the content in the docs actually does originate from our various blogs. The entire getting started tutorial was written by Rob Allen for his website/blog. He graciously contributed the entire thing to the documentation for free, no strings attached. I wrote Zend\ModuleManager and had an entire blog series drafted on how it works. Guess where you can find all that content? http://framework.zend.com/manual/2.2/en/modules/zend.module-manager.intro.html

Not to mention that there's an intrinsic value to the blogging community covering various topics. It's advantageous to have certain topics covered by multiple authors from multiple perspectives. I realize this is not what you're suggesting, but I'd argue that if all of those who are active bloggers on ZF2 converted our blogging time into solely working on the documentation and ceased blogging, it would actually be quite detrimental to the community as a whole. The diversity and availability of ZF2 content is a good thing.

I don't believe it was your intent, but your message made it out that these contributors and bloggers are doing a disservice for having blogs and not contributing more to the docs. Please just understand that all of us donate our time (sometimes massive, massive amounts of it) on a volunteer basis, whether that's by blogging, writing official docs, or contributing to the framework itself. We all do it to help the community as a whole, so please keep that in mind and try to keep your criticism constructive and positive.

That said, are our docs as good as they could be? No. Could we use a lot of better, more contextual MVC examples in the docs? Sure. I haven't seen anyone debate that. It's not even a question.

--
Evan Coury
Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

zburnham


On Jun 19, 2013, at 7:15 AM, Evan Coury <[hidden email]> wrote:



On Wed, Jun 19, 2013 at 12:56 AM, Marc Tempelmeier <[hidden email]> wrote:

Hi,

the problem right there I see every day in my company. They simply don´t want to search good examples.

The second argument against that is, how do you know if that are good examples in the first place?

You can spot that, beginners don´t!

In many companies they people don´t have time to educate themselfs much. They have to have a good

Documentation with _good_ examples.

I don´t get why everyone here is refering to other places or their blogs for that. They is _no reson_ to

Prefer multiple blogs etc. over examples on the official site.

Patches are welcome.  If you don't feel like the documentation is adequate, or could be improved, there is nothing stopping you from contributing yourself.  (I am not blameless here; I owe the docs some verbiage myself.)
Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

Spabby
+1 Zachary

The docs are written by contributors, if you think they have problems, please submit PR, I'm begging you!

G


On Wed, Jun 19, 2013 at 1:56 PM, Zachary Burnham <[hidden email]> wrote:


On Jun 19, 2013, at 7:15 AM, Evan Coury <[hidden email]> wrote:



On Wed, Jun 19, 2013 at 12:56 AM, Marc Tempelmeier <[hidden email]> wrote:

Hi,

the problem right there I see every day in my company. They simply don´t want to search good examples.

The second argument against that is, how do you know if that are good examples in the first place?

You can spot that, beginners don´t!

In many companies they people don´t have time to educate themselfs much. They have to have a good

Documentation with _good_ examples.

I don´t get why everyone here is refering to other places or their blogs for that. They is _no reson_ to

Prefer multiple blogs etc. over examples on the official site.

Patches are welcome.  If you don't feel like the documentation is adequate, or could be improved, there is nothing stopping you from contributing yourself.  (I am not blameless here; I owe the docs some verbiage myself.)

Reply | Threaded
Open this post in threaded view
|

AW: [zf-contributors] Starting the 3.0 branch

Marc Tempelmeier
In reply to this post by EvanDotPro

On Wed, Jun 19, 2013 at 12:56 AM, Marc Tempelmeier <[hidden email]> wrote:

Hi,

 

the problem right there I see every day in my company. They simply don´t want to search good examples.

The second argument against that is, how do you know if that are good examples in the first place?

You can spot that, beginners don´t!

 

This is a very general problem in software development -- it's precisely why I tell most smaller clients to always make sure they have at least one senior developer on staff to supplement their junior developers. If a company thinks they are saving money by employing all junior developers, they'll quickly learn that it's not the case; likely on their second or third re-write. I see it all the time -- in fact, it's usually why companies end up coming to me in the first place. If you can't afford a full time senior developer, you've pointed out a perfect example of why you should at minimum contract one as an advisor to help with these sort of things. This is getting off topic, but the problem you just described is something I see all too often, and it's a problem that's easily avoidable.

 

In many companies they people don´t have time to educate themselfs much. They have to have a good

Documentation with _good_ examples.

I don´t get why everyone here is refering to other places or their blogs for that. They is _no reson_ to

Prefer multiple blogs etc. over examples on the official site.

 

First of all, a good subscription list of blogs is imperative to following any topic you're trying to keep up with, technical or otherwise. If you're trying to be a ZF2 developer and not following at least a few blogs, I'd argue you're not doing your part to help yourself, your company, and your project succeed. Anyone who hasn't should get their RSS readers out and start subscribing: http://framework.zend.com/participate/blogs

 

Keep in mind that a lot of the content in the docs actually does originate from our various blogs. The entire getting started tutorial was written by Rob Allen for his website/blog. He graciously contributed the entire thing to the documentation for free, no strings attached. I wrote Zend\ModuleManager and had an entire blog series drafted on how it works. Guess where you can find all that content? http://framework.zend.com/manual/2.2/en/modules/zend.module-manager.intro.html

 

Not to mention that there's an intrinsic value to the blogging community covering various topics. It's advantageous to have certain topics covered by multiple authors from multiple perspectives. I realize this is not what you're suggesting, but I'd argue that if all of those who are active bloggers on ZF2 converted our blogging time into solely working on the documentation and ceased blogging, it would actually be quite detrimental to the community as a whole. The diversity and availability of ZF2 content is a good thing.

 

I don't believe it was your intent, but your message made it out that these contributors and bloggers are doing a disservice for having blogs and not contributing more to the docs. Please just understand that all of us donate our time (sometimes massive, massive amounts of it) on a volunteer basis, whether that's by blogging, writing official docs, or contributing to the framework itself. We all do it to help the community as a whole, so please keep that in mind and try to keep your criticism constructive and positive.

 

That said, are our docs as good as they could be? No. Could we use a lot of better, more contextual MVC examples in the docs? Sure. I haven't seen anyone debate that. It's not even a question.

 

--

Evan Coury

 

No, that was not my intent to critize that people blog. They should do that and I follow most of their blogs on my 3rd Screen with always open browser tabs.

But there are many people, who take a first look at something and if that is not acceptable or too complicated they will leave.

 

In my company are 7 PHP developer, just one (me) took the time to dive deeper into ZF1. I tried to educate the rest, but they simply can´t follow most of the time. We even began very very simple, trying with SOLID, OOP in general etc., but ZF1 was too difficult.

If you want to get those people into the boat, you have to explain the „why“ you do things. Or at least provide url where they can read the „why“. We discussed that in IRC (ocramius, hounddog, mac_nibblet etc.) and  came up with links in the documentation which point, as an example, to the website of Martin Fowler.

 

Back to the blogs, I really think that good blog posts should be linked in the documentation or better, worked into the documentation. The problem there is when things change, and that is the point where blogs became problematic. Blogs usually don´t change, because the authors didn´t catch up.

 

That are all barriers for „beginners“, they actively have to find good information and often, what they find doesn´t work. I heard that complaint multiple times here in my company. One official place is easier to keep updated than multiple blogs.

 

The diversity you could even keep in the documentation in a examples section. J

 

You are right that one has to follow multiple sources to keep informed, but to take ocramius example of the screwdriver, you don´t look at multiple blogs how to use it  ;)

 

The situation in most companies is not ideal, you said it yourself at the beginning. I´m just looking for ways to soften up the learning curve, I think we all aggree that this stuff is not easy. J

 

Marc

 

 

 

 

 

 

Reply | Threaded
Open this post in threaded view
|

Re: AW: [zf-contributors] Starting the 3.0 branch

localheinz
In reply to this post by Marc Tempelmeier
Hello Marc,

Documentation with _good_ examples.

I don´t get why everyone here is refering to other places or their blogs for that. They is _no reson_ to

Prefer multiple blogs etc. over examples on the official site.


I've mentioned this last year, when I was so upset about how ZF2 could be released as stable without accompanying documentation to get you started, and I fully agree with you. 

Although somewhat understandable that contributors want to take credit for their work, I personally believe it's more efficient - Pareto-efficient, that is - if their effort went into the documentation and not another blog post you have a hard time to find. 

Let's face it: if the documentation were excellent, you wouldn't have to search for answers to your ZF2-related questions anywhere else. 

It has been suggested to issue PRs to improve the documentation, but I find it difficult to do that if I haven't understood how a component works. 

I'd like to appeal to anyone who's contributed to issue PRs for documentation related to the contributions - and wish this was mandatory. 

The community at large would benefit a lot.

Bear in mind also, that the community is more than the people

* hanging around on IRC
* participating on the ML
* contributing on Github


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: AW: [zf-contributors] Starting the 3.0 branch

Gregory
I started programming when I was 8 years old, I failed my first programming course because of the little to no documentation. I was taught that coding is 80% documentation regardless of how good it is.

For it to be an enterprise level framework, there has to be Zend driven documentation, they are the fall back support when all else fails and companies needs assurance. On top of which, good documentation alone will drive actual code development and bug fixes.



On Jun 19, 2013, at 5:32 PM, Andreas Möller <[hidden email]> wrote:

Hello Marc,

Documentation with _good_ examples.

I don´t get why everyone here is refering to other places or their blogs for that. They is _no reson_ to

Prefer multiple blogs etc. over examples on the official site.


I've mentioned this last year, when I was so upset about how ZF2 could be released as stable without accompanying documentation to get you started, and I fully agree with you. 

Although somewhat understandable that contributors want to take credit for their work, I personally believe it's more efficient - Pareto-efficient, that is - if their effort went into the documentation and not another blog post you have a hard time to find. 

Let's face it: if the documentation were excellent, you wouldn't have to search for answers to your ZF2-related questions anywhere else. 

It has been suggested to issue PRs to improve the documentation, but I find it difficult to do that if I haven't understood how a component works. 

I'd like to appeal to anyone who's contributed to issue PRs for documentation related to the contributions - and wish this was mandatory. 

The community at large would benefit a lot.

Bear in mind also, that the community is more than the people

* hanging around on IRC
* participating on the ML
* contributing on Github


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: AW: [zf-contributors] Starting the 3.0 branch

localheinz
Hello Greg,


> I started programming when I was 8 years old, I failed my first programming course because of the little to no documentation. I was taught that coding is 80% documentation regardless of how good it is.
>
> For it to be an enterprise level framework, there has to be Zend driven documentation, they are the fall back support when all else fails and companies needs assurance. On top of which, good documentation alone will drive actual code development and bug fixes.

There's hardly more to add to what you've said.


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: AW: [zf-contributors] Starting the 3.0 branch

Richie Bartlett
Hello all,
   If you guys want an example of a very well structured and easy-to-follow documented framework, I would recommend looking at the fantastic job that Sencha.com has done for ExtJS! Their docs even come with bits of example code illustrating how it works. I had a hard time with ExtJS in the early days until they released an excellent examples page.
   Just my half-cent for your consideration.

iPhoneから送信
バートレット理路
Http://RichieBartlett.com
�090-6493-1691

Reply | Threaded
Open this post in threaded view
|

Re: AW: [zf-contributors] Starting the 3.0 branch

Spabby
A bad workman always blames the docs. 


On Thu, Jun 20, 2013 at 8:00 AM, Richie Bartlett <[hidden email]> wrote:
Hello all,
   If you guys want an example of a very well structured and easy-to-follow documented framework, I would recommend looking at the fantastic job that Sencha.com has done for ExtJS! Their docs even come with bits of example code illustrating how it works. I had a hard time with ExtJS in the early days until they released an excellent examples page.
   Just my half-cent for your consideration.

iPhoneから送信
バートレット理路
Http://RichieBartlett.com
�090-6493-1691


Reply | Threaded
Open this post in threaded view
|

Re: AW: [zf-contributors] Starting the 3.0 branch

Spabby
On a serious note, this topic has diverged _way_ off topic, if you'd like to discuss the doc failings, please do so in a more relevant thread. At the moment I would like to propose re-writing Zend\Log so it's PSR-3 compliant.

G


On Thu, Jun 20, 2013 at 8:36 AM, Gary Hockin <[hidden email]> wrote:
A bad workman always blames the docs. 


On Thu, Jun 20, 2013 at 8:00 AM, Richie Bartlett <[hidden email]> wrote:
Hello all,
   If you guys want an example of a very well structured and easy-to-follow documented framework, I would recommend looking at the fantastic job that Sencha.com has done for ExtJS! Their docs even come with bits of example code illustrating how it works. I had a hard time with ExtJS in the early days until they released an excellent examples page.
   Just my half-cent for your consideration.

iPhoneから送信
バートレット理路
Http://RichieBartlett.com
�090-6493-1691



Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

localheinz
In reply to this post by Spabby
> A bad workman always blames the docs.

You've surely never had to use any docs, have you?


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

localheinz
In reply to this post by Spabby
> On a serious note, this topic has diverged _way_ off topic, if you'd like to discuss the doc failings, please do so in a more relevant thread. At the moment I would like to propose re-writing Zend\Log so it's PSR-3 compliant.

I disagree. Documentation is as relevant as any other component of a project.

A number of threads have been started concerning the quality of documentation, but obviously, a great number of contributors do not care much about it.

Have a look right here

* https://github.com/zendframework/zf2-documentation/graphs/contributors
* https://github.com/zendframework/zf2/graphs/contributors

Do you notice something?


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

Spabby
The fact that you'd like better docs has been captured. Do we need to discuss the apparent failings of the existing docs to discuss what needs to be changed for 3.0. I think not. The purpose of this thread is to propose what you would like to see in 3.0. If some people spent as much time and effort submitting PR as they did moaning and whinging then the docs would be in a much better state.


On Thu, Jun 20, 2013 at 8:43 AM, Andreas Möller <[hidden email]> wrote:
> On a serious note, this topic has diverged _way_ off topic, if you'd like to discuss the doc failings, please do so in a more relevant thread. At the moment I would like to propose re-writing Zend\Log so it's PSR-3 compliant.

I disagree. Documentation is as relevant as any other component of a project.

A number of threads have been started concerning the quality of documentation, but obviously, a great number of contributors do not care much about it.

Have a look right here

* https://github.com/zendframework/zf2-documentation/graphs/contributors
* https://github.com/zendframework/zf2/graphs/contributors

Do you notice something?


Best regards,

Andreas

Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

Spabby
In reply to this post by localheinz
Have a look right here

https://github.com/zendframework/zf2-documentation/graphs/contributors
https://github.com/zendframework/zf2/graphs/contributors

Do you notice something?

You've made 14 commits on docs, and 44 on the main project, therefore you're as guilty as everyone else of contributing more to the main project than the docs?


On Thu, Jun 20, 2013 at 8:43 AM, Andreas Möller <[hidden email]> wrote:
> On a serious note, this topic has diverged _way_ off topic, if you'd like to discuss the doc failings, please do so in a more relevant thread. At the moment I would like to propose re-writing Zend\Log so it's PSR-3 compliant.

I disagree. Documentation is as relevant as any other component of a project.

A number of threads have been started concerning the quality of documentation, but obviously, a great number of contributors do not care much about it.

Have a look right here

* https://github.com/zendframework/zf2-documentation/graphs/contributors
* https://github.com/zendframework/zf2/graphs/contributors

Do you notice something?


Best regards,

Andreas

Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

Marco Pivetta
In reply to this post by Spabby
Another idea is to drop Zend\Memory from the main repo: does anybody even know what that thing does?

On 20 June 2013 09:48, Gary Hockin <[hidden email]> wrote:
If some people spent as much time and effort submitting PR as they did moaning and whinging then the docs would be in a much better state.

Where do I sign this?

Seriously, give it a rest! People here are picking work for 3.x components - if docs is your problem with 3.x, pick it as YOUR work to be done.


Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

localheinz
In reply to this post by Spabby
> The fact that you'd like better docs has been captured.

It's not being dealt with, obviously.

> Do we need to discuss the apparent failings of the existing docs to discuss what needs to be changed for 3.0. I think not.

You don't have to. I think it needs to be discussed, and the discussion should have some consequences.

> The purpose of this thread is to propose what you would like to see in 3.0.

I'd like to see better documentation. A lot of people feel the same.

> If some people spent as much time and effort submitting PR as they did moaning and whinging then the docs would be in a much better state.

Documentation should be provided by those who contribute, and not be those struggling how to understand how components work. That's the point.


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

Spabby
In reply to this post by Spabby
I'm being flippant by the way, I appear to have been drawn into this discussion, so I guess I'd better give some reasons.

1. The quickstart is excellent, kudos to Rob Allen and other contributors who wrote it. It does expect a certain level of knowledge of OO PHP, but we seriously can't expect to write introductory documentation for people with zero PHP experience. 
2. The individual component docs where the exist are adequate, and nothing more. This could be a problem if you're the kind of person who doesn't like looking at the source code of the components you are trying to use (in which case I'd argue you have a bigger problem than the quality of documentation).
3. I agree that more usable examples would be helpful. I've been saying the same thing in IRC for a few weeks.

So, in my own opinion, the docs do a fine job of getting you started, but then kind of leave you hanging. I suggest if we want to continue this discussion further, we do so in a new or existing thread.

G


On Thu, Jun 20, 2013 at 8:50 AM, Gary Hockin <[hidden email]> wrote:
You've made 14 commits on docs, and 44 on the main project, therefore you're as guilty as everyone else of contributing more to the main project than the docs?


On Thu, Jun 20, 2013 at 8:43 AM, Andreas Möller <[hidden email]> wrote:
> On a serious note, this topic has diverged _way_ off topic, if you'd like to discuss the doc failings, please do so in a more relevant thread. At the moment I would like to propose re-writing Zend\Log so it's PSR-3 compliant.

I disagree. Documentation is as relevant as any other component of a project.

A number of threads have been started concerning the quality of documentation, but obviously, a great number of contributors do not care much about it.

Have a look right here

* https://github.com/zendframework/zf2-documentation/graphs/contributors
* https://github.com/zendframework/zf2/graphs/contributors

Do you notice something?


Best regards,

Andreas


Reply | Threaded
Open this post in threaded view
|

Re: Starting the 3.0 branch

localheinz
In reply to this post by Spabby
You've made 14 commits on docs, and 44 on the main project, therefore you're as guilty as everyone else of contributing more to the main project than the docs?

I've committed small bug fixes that didn't need any documentation.

When I added a small component, I issued a PR with related documentation.

I don't see anything wrong with this.


Best regards,

Andreas
12345