Call for help: Documentation

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

Call for help: Documentation

weierophinney
Administrator
Hey, all --

We really, really, really need your help with documentation. A lot of
documentation was incomplete, or, worse, unwritten, for the stable
release.

I've tallied up the tasks here:

    https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

If you're not sure what you can do to contribute to the project, take
the above list as a roadmap. Even if you're more comfortable with code,
any little bit you can do with the docs will be of immense use to all
those who come in and read them later.

Thanks, everyone!

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic

Hi all!

This is just an idea, but hopefully would make easier for new devs, or devs who don't have that much knowledge of any or all components, but here goes...

Someone who is familiar with Component Foo, possibly the component's lead, sketch out the documentation,something like:

- intro section - write a short intro to component foo
- section a - write stuff about this
- section b - write stuff about that showing approach spam and approach ham with code examples

and so on. Now, if I know about section b, I can just write that, and someone else could write the other parts.

For a better example, take View. I don't even know what all parts does it have... But if someone would make a basic documentation "skeleton" for it, and I see section "Writing and using custom view helpers", I could submit a PR for that, because I already know that part. Again, if I'm not familiar with a section, I could probably figure it out by looking at the tests, API for it, trying it out on my own...

Does this make sense?

As for me, currently I could probably help with the documentation on Dom, Feed and Tag components in the coming days.

Thanks! :)

P.S.: Also, if there's a page explaining how to contribute to documentation, please spam the hell out of it on twitter/mailing list/irc/whatever :)

On 25 Sep 2012 20:18, "Matthew Weier O'Phinney" <[hidden email]> wrote:
Hey, all --

We really, really, really need your help with documentation. A lot of
documentation was incomplete, or, worse, unwritten, for the stable
release.

I've tallied up the tasks here:

    https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

If you're not sure what you can do to contribute to the project, take
the above list as a roadmap. Even if you're more comfortable with code,
any little bit you can do with the docs will be of immense use to all
those who come in and read them later.

Thanks, everyone!

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Wesley Overdijk
It makes perfect sense to me. Now it's like "WE NEED DOCS!" and I'm... Not sure on where to start. Having actual topics is a very good idea.

On 25 Sep 2012, at 22:11, Robert Basic wrote:

Hi all!

This is just an idea, but hopefully would make easier for new devs, or devs who don't have that much knowledge of any or all components, but here goes...

Someone who is familiar with Component Foo, possibly the component's lead, sketch out the documentation,something like:

- intro section - write a short intro to component foo
- section a - write stuff about this
- section b - write stuff about that showing approach spam and approach ham with code examples

and so on. Now, if I know about section b, I can just write that, and someone else could write the other parts.

For a better example, take View. I don't even know what all parts does it have... But if someone would make a basic documentation "skeleton" for it, and I see section "Writing and using custom view helpers", I could submit a PR for that, because I already know that part. Again, if I'm not familiar with a section, I could probably figure it out by looking at the tests, API for it, trying it out on my own...

Does this make sense?

As for me, currently I could probably help with the documentation on Dom, Feed and Tag components in the coming days.

Thanks! :)

P.S.: Also, if there's a page explaining how to contribute to documentation, please spam the hell out of it on twitter/mailing list/irc/whatever :)

On 25 Sep 2012 20:18, "Matthew Weier O'Phinney" <[hidden email]> wrote:
Hey, all --

We really, really, really need your help with documentation. A lot of
documentation was incomplete, or, worse, unwritten, for the stable
release.

I've tallied up the tasks here:

    https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

If you're not sure what you can do to contribute to the project, take
the above list as a roadmap. Even if you're more comfortable with code,
any little bit you can do with the docs will be of immense use to all
those who come in and read them later.

Thanks, everyone!

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc

Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Adam Lundrigan
In reply to this post by robertbasic

I think this is a fantastic idea.  I'm just now getting back into the ZF2 groove after 6 weeks of being MIA due to work and personal obligations, and would love to pitch in on docs and tutorials as I re-learn the components I need for my projects. The TODO file added my Matthew is a good start to know where effort is needed, but having the component creator/maintainer or someone experienced with that component sketch an outline of what the documentation should cover (or annotate any existing outdated docs to identify missing topics) would be very helpful.

--
Adam Lundrigan, B.Sc, ZCE
[hidden email]


On Tue, Sep 25, 2012 at 5:41 PM, Robert Basic <[hidden email]> wrote:

Hi all!

This is just an idea, but hopefully would make easier for new devs, or devs who don't have that much knowledge of any or all components, but here goes...

Someone who is familiar with Component Foo, possibly the component's lead, sketch out the documentation,something like:

- intro section - write a short intro to component foo
- section a - write stuff about this
- section b - write stuff about that showing approach spam and approach ham with code examples

and so on. Now, if I know about section b, I can just write that, and someone else could write the other parts.

For a better example, take View. I don't even know what all parts does it have... But if someone would make a basic documentation "skeleton" for it, and I see section "Writing and using custom view helpers", I could submit a PR for that, because I already know that part. Again, if I'm not familiar with a section, I could probably figure it out by looking at the tests, API for it, trying it out on my own...

Does this make sense?

As for me, currently I could probably help with the documentation on Dom, Feed and Tag components in the coming days.

Thanks! :)

P.S.: Also, if there's a page explaining how to contribute to documentation, please spam the hell out of it on twitter/mailing list/irc/whatever :)

On 25 Sep 2012 20:18, "Matthew Weier O'Phinney" <[hidden email]> wrote:
Hey, all --

We really, really, really need your help with documentation. A lot of
documentation was incomplete, or, worse, unwritten, for the stable
release.

I've tallied up the tasks here:

    https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

If you're not sure what you can do to contribute to the project, take
the above list as a roadmap. Even if you're more comfortable with code,
any little bit you can do with the docs will be of immense use to all
those who come in and read them later.

Thanks, everyone!

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc

Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
In reply to this post by robertbasic
-- Robert Basic <[hidden email]> wrote
(on Tuesday, 25 September 2012, 10:11 PM +0200):
> P.S.: Also, if there's a page explaining how to contribute to documentation,
> please spam the hell out of it on twitter/mailing list/irc/whatever :)

https://github.com/zendframework/zf2-documentation/blob/master/CONTRIBUTE.md

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
In reply to this post by robertbasic
-- Robert Basic <[hidden email]> wrote
(on Tuesday, 25 September 2012, 10:11 PM +0200):

> This is just an idea, but hopefully would make easier for new devs, or devs who
> don't have that much knowledge of any or all components, but here goes...
>
> Someone who is familiar with Component Foo, possibly the component's lead,
> sketch out the documentation,something like:
>
> - intro section - write a short intro to component foo
> - section a - write stuff about this
> - section b - write stuff about that showing approach spam and approach ham
> with code examples
>
> and so on. Now, if I know about section b, I can just write that, and someone
> else could write the other parts.

Well, one thing is that we did already accept a recommendation for doc
structure. Essentially, each component needs the following pages:

 - Overview
 - Quick Start (ideally showing usage within an application)
 - Configuration options
 - Available methods
 - Examples

This gets a little ambiguous when you a component has multiple classes,
obviously. In those cases, a page per class with the above can likely
work; if there are things like adapters, helpers, plugins, etc., a page
outlining what class(es) compose(s) them, etc., as well as a list of
links to a page outlining each plugin would be good.

I'll see if I can get a few of these established in the next few days.

> For a better example, take View. I don't even know what all parts does it
> have... But if someone would make a basic documentation "skeleton" for it, and
> I see section "Writing and using custom view helpers", I could submit a PR for
> that, because I already know that part. Again, if I'm not familiar with a
> section, I could probably figure it out by looking at the tests, API for it,
> trying it out on my own...
>
> Does this make sense?
>
> As for me, currently I could probably help with the documentation on Dom, Feed
> and Tag components in the coming days.
>
> Thanks! :)
>
> P.S.: Also, if there's a page explaining how to contribute to documentation,
> please spam the hell out of it on twitter/mailing list/irc/whatever :)
>
> On 25 Sep 2012 20:18, "Matthew Weier O'Phinney" <[hidden email]> wrote:
>
>     Hey, all --
>
>     We really, really, really need your help with documentation. A lot of
>     documentation was incomplete, or, worse, unwritten, for the stable
>     release.
>
>     I've tallied up the tasks here:
>
>         https://github.com/zendframework/zf2-documentation/blob/master/TODO.md
>
>     If you're not sure what you can do to contribute to the project, take
>     the above list as a roadmap. Even if you're more comfortable with code,
>     any little bit you can do with the docs will be of immense use to all
>     those who come in and read them later.
>
>     Thanks, everyone!
>
>     --
>     Matthew Weier O'Phinney
>     Project Lead            | [hidden email]
>     Zend Framework          | http://framework.zend.com/
>     PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
>

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney

Just a note that I'm starting work on Zend\Feed. Will bug Pàdraic about the current state of the docs.

On 25 Sep 2012 20:18, "Matthew Weier O'Phinney" <[hidden email]> wrote:
Hey, all --

We really, really, really need your help with documentation. A lot of
documentation was incomplete, or, worse, unwritten, for the stable
release.

I've tallied up the tasks here:

    https://github.com/zendframework/zf2-documentation/blob/master/TODO.md

If you're not sure what you can do to contribute to the project, take
the above list as a roadmap. Even if you're more comfortable with code,
any little bit you can do with the docs will be of immense use to all
those who come in and read them later.

Thanks, everyone!

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Andreas Möller
I'm just getting my "feet wet" - as they say - with ZF2 and don't mind to fix a few issues with the documentation while I come across them.


Happy forking and pulling,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Artur Bodera
In reply to this post by weierophinney
On Tue, Sep 25, 2012 at 8:17 PM, Matthew Weier O'Phinney <[hidden email]> wrote:
Hey, all --

We really, really, really need your help with documentation. A lot of
documentation was incomplete, or, worse, unwritten, for the stable
release.

I've tallied up the tasks here:

    https://github.com/zendframework/zf2-documentation/blob/master/TODO.md


What exactly is "incomplete" in the documentation of Console ?


-- 
      __
     /.)\   +48 695 600 936
     \(./   [hidden email]




 
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

weierophinney
Administrator
-- Artur Bodera <[hidden email]> wrote
(on Wednesday, 26 September 2012, 06:20 PM +0200):

> On Tue, Sep 25, 2012 at 8:17 PM, Matthew Weier O'Phinney <[hidden email]>
> wrote:
>     We really, really, really need your help with documentation. A lot of
>     documentation was incomplete, or, worse, unwritten, for the stable
>     release.
>
>     I've tallied up the tasks here:
>
>         https://github.com/zendframework/zf2-documentation/blob/master/TODO.md
>
>
>
> What exactly is "incomplete" in the documentation of Console ?

It's not linked properly into the manual, so next/prev page links are
missing. Additionally, we need an end-to-end example -- right now, you
have to go back and forth between pages to learn how to string it all
together to work correctly. I've been playing with Console heavily the
past week, so I'll likely write this.

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
On 26 September 2012 19:25, Matthew Weier O'Phinney <[hidden email]> wrote:

> It's not linked properly into the manual, so next/prev page links are
> missing.

I've noticed this for Zend\Feed now while I'm working on it. I added
the Zend\Feed links to the main ToC, but not sure what I need to edit
to get the prev/next links? If anyone knows this, please feel free to
share it :)
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
On 26 September 2012 19:36, Robert Basic <[hidden email]> wrote:
> On 26 September 2012 19:25, Matthew Weier O'Phinney <[hidden email]> wrote:
>
>> It's not linked properly into the manual, so next/prev page links are
>> missing.
>
> I've noticed this for Zend\Feed now while I'm working on it. I added
> the Zend\Feed links to the main ToC, but not sure what I need to edit
> to get the prev/next links? If anyone knows this, please feel free to
> share it :)

To answer my own question: in docs/languages/en/index.rst file, there
is a ".. toctree::" section, starting on line 11. Add the "links" to
this part too, and the prev/next link will be also generated.

--
~Robert Basic;
http://robertbasic.com/
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Andreas Möller
Apart from examples in the documentation where I believe the intention is to save space, I have noticed that in the code base there are a number of methods in classes and interfaces that are not documented in that they have not been provided with an accompanying PhpDoc method level comment.

Shouldn't these be provided in all cases?


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
I'm picking up fixing Zend\Json docs as my next task.

On 25 September 2012 20:17, Matthew Weier O'Phinney <[hidden email]> wrote:

> Hey, all --
>
> We really, really, really need your help with documentation. A lot of
> documentation was incomplete, or, worse, unwritten, for the stable
> release.
>
> I've tallied up the tasks here:
>
>     https://github.com/zendframework/zf2-documentation/blob/master/TODO.md
>
> If you're not sure what you can do to contribute to the project, take
> the above list as a roadmap. Even if you're more comfortable with code,
> any little bit you can do with the docs will be of immense use to all
> those who come in and read them later.
>
> Thanks, everyone!
>
> --
> Matthew Weier O'Phinney
> Project Lead            | [hidden email]
> Zend Framework          | http://framework.zend.com/
> PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc



--
~Robert Basic;
http://robertbasic.com/
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
May I ask what's wrong with the Zend\Dom documentation? Apart from the
1 sentence Introduction page having no point :)

Also, picking up Zend\XmlRpc for today.

On 25 September 2012 20:17, Matthew Weier O'Phinney <[hidden email]> wrote:

> Hey, all --
>
> We really, really, really need your help with documentation. A lot of
> documentation was incomplete, or, worse, unwritten, for the stable
> release.
>
> I've tallied up the tasks here:
>
>     https://github.com/zendframework/zf2-documentation/blob/master/TODO.md
>
> If you're not sure what you can do to contribute to the project, take
> the above list as a roadmap. Even if you're more comfortable with code,
> any little bit you can do with the docs will be of immense use to all
> those who come in and read them later.
>
> Thanks, everyone!
>
> --
> Matthew Weier O'Phinney
> Project Lead            | [hidden email]
> Zend Framework          | http://framework.zend.com/
> PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc



--
~Robert Basic;
http://robertbasic.com/
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
Zend\Server docs are next up for me.
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

robertbasic
In reply to this post by weierophinney
Guess what? I'm picking up Zend\Text :)
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Ralf Eggert
In reply to this post by weierophinney
Hi,

I will start to work on Zend\Filter now.

Regards,

Ralf
Reply | Threaded
Open this post in threaded view
|

RE: Call for help: Documentation

BullfrogBlues
A couple of quick questions on PHPDocs:

* Should `@return void` be required or be removed, is it necessary?

* Should all fluent interfaces be commented `@return WhateverObject Provides fluent interface`?

* What are the standards, if any, with `@triggers`?

* Should specifying the method name at the top of a method PHPDoc be
              discouraged, or required? It's pretty much redundant isn't it?

        **Example**

            /**
             * This is primarily for unit testing, but could have other uses.
             *
             * @return array
             */
            public function getPaths() {/* .. */}

        OR

            /**
             * getPaths
             *
             * This is primarily for unit testing, but could have other uses.
             *
             * @return array
             */
            public function getPaths() {/* .. */}

--
Gerard
Del
Reply | Threaded
Open this post in threaded view
|

Re: Call for help: Documentation

Del

Opinions here from long experience with phpDocs rather than the official
consensus of the community: :)

 > * Should `@return void` be required or be removed, is it necessary?

It should be required.  There are API documentation analysis tools that
will allow you to tabulate the return types where they are given.  Where
they are not given, the tools can't help you.

> * Should all fluent interfaces be commented `@return WhateverObject
> Provides fluent interface`?

Yes, for the same reason as above.

> * What are the standards, if any, with `@triggers`?

NFI, sorry.

> * Should specifying the method name at the top of a method PHPDoc be
>                discouraged, or required? It's pretty much redundant
> isn't it?

If you use phpDoc then the single line at the top is made into a header
and bolded, and placed under the method name.  Flow on lines from that
are ignored.  If you use another API documenting tool (e.g. apidoc) then
it's not required, but it's become a de facto standard because of
phpDoc's usage.

Therefore, this:

>              /**
>               * getPaths
>               *
>               * This is primarily for unit testing, but could have other
> uses.
>               *
>               * @return array
>               */

Becomes:

--
getPaths

*getPaths*  <--bold

This is primarily for unit testing, but could have other uses.
--

To my way of thinking, repeating the method name as a sub-heading is
redundant, but a subheading is useful as a longer (1 line) description
of the function.  So it should in fact be:

/**
  * This is primarily for unit testing.
  *
  * This function is primarily for unit testing but could have other
  * uses, such as bla bla, bla bla bla, or perhaps something else.
  *
  * @return array
  */

That will result in the following output:

--
getPaths

*This is primarily for unit testing.*  <--bold

This function is primarily for unit testing but could have other
uses, such as bla bla, bla bla bla, or perhaps something else
--

In particular, this is wrong:

/**
  * This function is primarily for unit testing but could have other
  * uses, such as bla bla, bla bla bla, or perhaps something else.
  *
  * @return array
  */

... because it will result in this:

--
getPaths

*This function is primarily for unit testing but could have other*
(bold, makes no sense).

uses, such as bla bla, bla bla bla, or perhaps something else
--

So the primary reason why the method name is specified at the top of the
docblock is to ensure that phpDoc only digests the single header line,
but in fact it should be a single line header describing the method
without regard to the method name.

Del

1234