100% Overhaul of the QuickStart

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

100% Overhaul of the QuickStart

manuakasam
This post has NOT been accepted by the mailing list yet.
Hey guys,

danizord and I are currently in the process of figuring out a good way to do an 100% overhaul of the QuickStart part of the documentation. Though at the same time it may not be a replacement but just an additional part of the docs that just goes way, way deeper into explaining things than the current documentation does.

Get a first glimpse of writing/teaching style here:
https://github.com/manuakasam/ZF2_3_QuickStart_Rewrite/blob/master/docs/writing_first_module.md
https://github.com/manuakasam/ZF2_3_QuickStart_Rewrite/blob/master/outline.md

Why all of this?

To be honest: our documentation is not good. It serves a purpose but by no means does it actually teach you too much. This is by no means to disapprove the work the current authors have done, but it's a fact that it's just no good to people who get into MVC Frameworks for the first time.

I'm currently introducing a trainee at work into ZF2 and damn, the docs don't help. Once we run into error messages and i explain to him what the message means and why it is there, he begins to tie all points of the application together.

And this is exactly what I want to achieve with an overhaul of the QuickStart. I want to go into freaking deep detail as to "how to write a modul". We should cover best practices, actually introduce people into core concepts of zf2 (proper DI, hydrators, better use of forms, etc...)

What do I want from you?

Well, I want feedback, naturally. But to be more precise, I want to get feedback on the writing style and contents. On the level of detail I intend to write this whole thing. The way I address the speaker and use "we" or "us" or "I". All the small details.

Note: This whole thing will be written completely in githubs .md format. I have no intentions of writing this in our documentations .rst format at the time of writing. This port will happen once everything is finished.
Reply | Threaded
Open this post in threaded view
|

Re: 100% Overhaul of the QuickStart

Oliver Koenig
This post has NOT been accepted by the mailing list yet.
Hi Sam,

wow, great, thanks for the effort!
Finally someone brave does something about it! :-)

Just a quick feedback on what I was missing in the current docs, I'm also a newbie and working my way through the framework, and the docs help a little sometimes when I need some specifics, but not for understanding the principles and the structure, and not for getting started at all.

1. Graphical representations of the architectural structure would be very very nice to help understand the system. I know it's a lot of work and I understand that no one wants to do it or have the time to do it, including myself, but many would benefit a lot from it.

2. Detailed explanation of the bootstrapping sequence. I found a very good one in the book "Web Development with Zend Framework 2" by Michael Romer. I can email it to you, it can serve as an inspiration, or you might consider including the excerpt as is if the author gives his permission.

3. Explanation (and discussion?) of general software design principles used in the framework, e.g. dependency injection, why to do it and why not to work around it. Other principles used in the framework, too, e.g. "separations of concerns", "inverson of control", "convention over contract", and several others, I just don't know them well enough to write a good list here.

4. Explanation of the PSR-x coding styles and the class autoloader and how the latter depends on the former.

Something else towards the same goal of helping new ZF2 (and ZF3) developers would be more Skeleton Applications, using more features of the framework, and more resembling full-fledged real-world applications. That is definitely not part of the docs, though, but something that could be a concerted effort, with a separate project and sub-projects on GitHub. Perhaps it would be an idea to start with some real-world applications that ZF2 developers created for real-world use, and strip them down and remove company branding. Shouldn't be too difficult to achieve.

Yeah, I know, it's all a lot of work involved, I just wanted to give some feedback to feed the discussion about what people might want or need to get more easily started in the framework.

Thanks & regards,
Oliver


On 2014-02-05 09:24, manuakasam [via Zend Framework Community] wrote:
Hey guys,

danizord and I are currently in the process of figuring out a good way to do an 100% overhaul of the QuickStart part of the documentation. Though at the same time it may not be a replacement but just an additional part of the docs that just goes way, way deeper into explaining things than the current documentation does.

Get a first glimpse of writing/teaching style here:
https://github.com/manuakasam/ZF2_3_QuickStart_Rewrite/blob/master/docs/writing_first_module.md
https://github.com/manuakasam/ZF2_3_QuickStart_Rewrite/blob/master/outline.md

Why all of this?

To be honest: our documentation is not good. It serves a purpose but by no means does it actually teach you too much. This is by no means to disapprove the work the current authors have done, but it's a fact that it's just no good to people who get into MVC Frameworks for the first time.

I'm currently introducing a trainee at work into ZF2 and damn, the docs don't help. Once we run into error messages and i explain to him what the message means and why it is there, he begins to tie all points of the application together.

And this is exactly what I want to achieve with an overhaul of the QuickStart. I want to go into freaking deep detail as to "how to write a modul". We should cover best practices, actually introduce people into core concepts of zf2 (proper DI, hydrators, better use of forms, etc...)

What do I want from you?

Well, I want feedback, naturally. But to be more precise, I want to get feedback on the writing style and contents. On the level of detail I intend to write this whole thing. The way I address the speaker and use "we" or "us" or "I". All the small details.

Note: This whole thing will be written completely in githubs .md format. I have no intentions of writing this in our documentations .rst format at the time of writing. This port will happen once everything is finished.


If you reply to this email, your message will be added to the discussion below:
http://zend-framework-community.634137.n4.nabble.com/100-Overhaul-of-the-QuickStart-tp4661604.html
To start a new topic under ZF Contributor, email [hidden email]
To unsubscribe from Zend Framework Community, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: 100% Overhaul of the QuickStart

manuakasam
This post has NOT been accepted by the mailing list yet.
Hey Oliver,

almost all points you've mentioned will find their places inside the new docs that I intend to write. 

#1 will be a big thing and is planned out for every change on the file system. It's just something that will follow in late.

#2 That's not something for a QuickStart or a ZF2 0->100. It can totally belong to an appendix where several topics are explained in detail, but ultimately it's outside of the scope of an "introduction" (at least that's my point, others may outweight me tho ;))

#3 These things will be covered when we find matching topics inside the creation of the module. Ultimately there will be two big parts. One that introduces people to general ZF2 stuff. and then something like a "QuickStart - Refactoring best practices" where we cover some of the topics you've mentioned in detail.

#4 PSR-0 will be covered in detail inside the appendix section. It's just not something that really belongs to ZF2 per sé. The other PSR-stuff can be mentioned at hints but are outside of the scope of the documentation.


Thanks for your feedback.



2014-02-05 Oliver Koenig [via Zend Framework Community] <[hidden email]>:
Hi Sam,

wow, great, thanks for the effort!
Finally someone brave does something about it! :-)

Just a quick feedback on what I was missing in the current docs, I'm also a newbie and working my way through the framework, and the docs help a little sometimes when I need some specifics, but not for understanding the principles and the structure, and not for getting started at all.

1. Graphical representations of the architectural structure would be very very nice to help understand the system. I know it's a lot of work and I understand that no one wants to do it or have the time to do it, including myself, but many would benefit a lot from it.

2. Detailed explanation of the bootstrapping sequence. I found a very good one in the book "Web Development with Zend Framework 2" by Michael Romer. I can email it to you, it can serve as an inspiration, or you might consider including the excerpt as is if the author gives his permission.

3. Explanation (and discussion?) of general software design principles used in the framework, e.g. dependency injection, why to do it and why not to work around it. Other principles used in the framework, too, e.g. "separations of concerns", "inverson of control", "convention over contract", and several others, I just don't know them well enough to write a good list here.

4. Explanation of the PSR-x coding styles and the class autoloader and how the latter depends on the former.

Something else towards the same goal of helping new ZF2 (and ZF3) developers would be more Skeleton Applications, using more features of the framework, and more resembling full-fledged real-world applications. That is definitely not part of the docs, though, but something that could be a concerted effort, with a separate project and sub-projects on GitHub. Perhaps it would be an idea to start with some real-world applications that ZF2 developers created for real-world use, and strip them down and remove company branding. Shouldn't be too difficult to achieve.

Yeah, I know, it's all a lot of work involved, I just wanted to give some feedback to feed the discussion about what people might want or need to get more easily started in the framework.

Thanks & regards,
Oliver


On 2014-02-05 09:24, manuakasam [via Zend Framework Community] wrote:
Hey guys,

danizord and I are currently in the process of figuring out a good way to do an 100% overhaul of the QuickStart part of the documentation. Though at the same time it may not be a replacement but just an additional part of the docs that just goes way, way deeper into explaining things than the current documentation does.

Get a first glimpse of writing/teaching style here:
https://github.com/manuakasam/ZF2_3_QuickStart_Rewrite/blob/master/docs/writing_first_module.md
https://github.com/manuakasam/ZF2_3_QuickStart_Rewrite/blob/master/outline.md

Why all of this?

To be honest: our documentation is not good. It serves a purpose but by no means does it actually teach you too much. This is by no means to disapprove the work the current authors have done, but it's a fact that it's just no good to people who get into MVC Frameworks for the first time.

I'm currently introducing a trainee at work into ZF2 and damn, the docs don't help. Once we run into error messages and i explain to him what the message means and why it is there, he begins to tie all points of the application together.

And this is exactly what I want to achieve with an overhaul of the QuickStart. I want to go into freaking deep detail as to "how to write a modul". We should cover best practices, actually introduce people into core concepts of zf2 (proper DI, hydrators, better use of forms, etc...)

What do I want from you?

Well, I want feedback, naturally. But to be more precise, I want to get feedback on the writing style and contents. On the level of detail I intend to write this whole thing. The way I address the speaker and use "we" or "us" or "I". All the small details.

Note: This whole thing will be written completely in githubs .md format. I have no intentions of writing this in our documentations .rst format at the time of writing. This port will happen once everything is finished.


If you reply to this email, your message will be added to the discussion below:
http://zend-framework-community.634137.n4.nabble.com/100-Overhaul-of-the-QuickStart-tp4661604.html
To start a new topic under ZF Contributor, email [hidden email]
To unsubscribe from Zend Framework Community, click here.
NAML




If you reply to this email, your message will be added to the discussion below:
http://zend-framework-community.634137.n4.nabble.com/100-Overhaul-of-the-QuickStart-tp4661604p4661607.html
To unsubscribe from 100% Overhaul of the QuickStart, click here.
NAML

jah
Reply | Threaded
Open this post in threaded view
|

Re: 100% Overhaul of the QuickStart

jah
This post has NOT been accepted by the mailing list yet.
Love the Exhaustive style Documentation you're working on. I would also appreciate if the rest of the components can also be written in such a way.

Keep up the good work! Thanks!
Reply | Threaded
Open this post in threaded view
|

Re: 100% Overhaul of the QuickStart

manuakasam
This post has NOT been accepted by the mailing list yet.
I now have finished the first draft of the second chapter of my documentational tutorial. It introduces the reader into the service layer and the service manager.

In my opinion this topic should come before we introduce people to actual backends for services. My intention is to introduce the reader slowly into the ServiceManager with a simple and "one" example. Tell the user in a simple fashion what factories and invokables are about and simply bring little life into our aplication.

the next chapter will be pretty small and i dont know if it will remain its own chapter. Basically i will introduce the user into routing, child-routes, routeparameters, etc... to be able to display data for a single album.

You can find the 2nd chapter here:
Reply | Threaded
Open this post in threaded view
|

Re: 100% Overhaul of the QuickStart

dennis-fedco
This post has NOT been accepted by the mailing list yet.
In reply to this post by manuakasam
just a little comment I want to add at this time -- my *big* realization of ZF2 was that most things in ZF2 are Configured opposed to written..

When just learning ZF2, it is a framework that you bend to your will by configuring existing ZF2 classes and modules and adding bits and pieces of your own glue code.  You are not writing any of your own code really - if you do, it is mostly glue code or configuration and very little of your actual hard-hitting business logic.

This mindset may help when learning ZF2.

i.e. How do I add a form?
Step 1:   go to this HTML and type this piece of cod..... wait no, first, learn that there is an existing set of classes, learn how they work together, learn about who calls what and why. Get the bigger picture.  How events work, these are the techniques to know and use, there are some best practices that already exist and are still evolving.  There are configuration classes that you can use.  Think about how this form will add into your existing or emerging application architecture.

Now, you can go to this, this, and this class, this, this and this configuration file, and add this, this and this, piece of code, and now you have your form....  maybe!
Reply | Threaded
Open this post in threaded view
|

Re: 100% Overhaul of the QuickStart

manuakasam
This post has NOT been accepted by the mailing list yet.
This weekend I will be writing the DB implementation of TableGateway. I have furthermore separated all chapters into a PR each to enable easier comments on specifics of the files.

Please guys, leave me as much feedback as possible, I need it ;-) It's all for a stronger community


Chapter 01 - Writing your first module

Chapter 02 - Services and the ServiceManager

Chapter 03 - Database and TableGateway implementation