How to improve the docs?

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

Re: How to improve the docs?

localheinz
Hello Frank,


> My opinion: The official api doc is horrible.

I agree.

Sorry, Gary!

I'm sure though that we can make it as nice as the other examples. What do you think?


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: How to improve the docs?

localheinz
In reply to this post by Pavel Kačer
>> Maybe it's really the best idea to improve the documentation *within*
>> the code. Then the documentation would be as close to the code as
>> possible and it would be a lot easier to review PRs both in terms of
>> documentation and code provided.
>
> This is what I wrote about a month ago to this mailing list and it got
> quite unnoticed. This is the best way to document separated components.

How should we get along with tackling this, everyone?

I think the most important thing to find out beforehand is

* How can we parse the API documentation to generate a nice looking documentation from it?

When that question is answered, I guess we should just go ahead and update the existing API documentation.


Best regards,

Andreas
Reply | Threaded
Open this post in threaded view
|

Re: How to improve the docs?

Bittarman
On Wednesday, 26 June 2013 at 11:30, Andreas Möller wrote:
Maybe it's really the best idea to improve the documentation *within*
the code. Then the documentation would be as close to the code as
possible and it would be a lot easier to review PRs both in terms of
documentation and code provided.

This is what I wrote about a month ago to this mailing list and it got
quite unnoticed. This is the best way to document separated components.

How should we get along with tackling this, everyone?

I think the most important thing to find out beforehand is

* How can we parse the API documentation to generate a nice looking documentation from it?

Well the answer to that is simple, parse it with phpdoc as we already do, but change the template to look nicer… the only problem is that "nicer" is subjective and we will never please everyone, nor is "nicer" really material to actually getting the content across, usability is far more important here. and as far as I can see, simply making the class list collapse correctly would be far more important than the soon to follow green vs blue, gradients vs no gradients argument soon to follow!
When that question is answered, I guess we should just go ahead and update the existing API documentation.


Best regards,

Andreas
Regards

Ryan
Reply | Threaded
Open this post in threaded view
|

Re: How to improve the docs?

localheinz
> Well the answer to that is simple, parse it with phpdoc as we already do, but change the template to look nicer… the only problem is that "nicer" is subjective and we will never please everyone, nor is "nicer" really material to actually getting the content across, usability is far more important here. and as far as I can see, simply making the class list collapse correctly would be far more important than the soon to follow green vs blue, gradients vs no gradients argument soon to follow!

In terms of usability I believe a search would be great, too.

I believe the presentation of the documentation should reflect - or better fit in - to the design of the current website.



Reply | Threaded
Open this post in threaded view
|

Re: How to improve the docs?

Jeremy Postlethwaite
What about code examples that have actual unit tests in a repository.

Nothing worse that copying examples that have errors :(

- Jeremy


On Wed, Jun 26, 2013 at 4:31 AM, Andreas Möller <[hidden email]> wrote:
> Well the answer to that is simple, parse it with phpdoc as we already do, but change the template to look nicer… the only problem is that "nicer" is subjective and we will never please everyone, nor is "nicer" really material to actually getting the content across, usability is far more important here. and as far as I can see, simply making the class list collapse correctly would be far more important than the soon to follow green vs blue, gradients vs no gradients argument soon to follow!

In terms of usability I believe a search would be great, too.

I believe the presentation of the documentation should reflect - or better fit in - to the design of the current website.




Reply | Threaded
Open this post in threaded view
|

Re: How to improve the docs?

Justin Martin
In reply to this post by localheinz
On 13-06-26 03:30 AM, Andreas Möller wrote:
Maybe it's really the best idea to improve the documentation *within*
the code. Then the documentation would be as close to the code as
possible and it would be a lot easier to review PRs both in terms of
documentation and code provided.
This is what I wrote about a month ago to this mailing list and it got
quite unnoticed. This is the best way to document separated components.
How should we get along with tackling this, everyone? 

I think the most important thing to find out beforehand is

* How can we parse the API documentation to generate a nice looking documentation from it?

When that question is answered, I guess we should just go ahead and update the existing API documentation.


Best regards,

Andreas

My suggestion would really be contingent upon some major changes to the structure of the documentation.

Gary and I had an outside conversation about basically starting a new, formalized documentation process which would make some major changes to how the documentation is handled.

First and foremost, I would like to see a change in the *format* of the documentation. By no means would I suggest scrapping RST, but what I would like to see is a move to a hybrid of Docbook and RST.
The reasons for this are plentiful, but first and foremost it is because RST is not a semantic documentation format. The chief issue with the current documentation is that it lacks clear and concise API documentation.
This is largely because RST offers no standard that I'm aware of for semantic definition of class/method/function information. I'm sure some skeleton for that could be hacked together, but it's really just overextending the usefulness of the format.

If you were to take a look at, say, http://svn.php.net/viewvc/phpdoc/en/trunk/reference/pdo/pdostatement/fetchall.xml?view=markup#l12, you can see how usefully semantic Docbook is.

This being said, I do *understand* why RST was picked for the documentation that ZF2 *does* have. It offers a simple format for "stream of consciousness" documentation that is simply not possible with Docbook. Writing Docbook markup requires a fair bit of foreknowledge, which acts as a substantial barrier to entry for new documentation contributors.

So, what I would recommend doing is creating a hybrid format for the documentation which makes use of Docbook for the semantic documentation of class structures, method calls and property/parameter information. Then, for examples, which the current documentation is basically a mash of, use RST in separate files which are then linked into the semantic documentation, in a format similar to how PHP's manual does it.

When a get some time, I'll see about putting together a proof of concept for one of the components in the framework (say, Stdlib), to demonstrate what I'm talking about, since documentation formats can be a bit esoteric.

Thanks,
Justin Martin
Reply | Threaded
Open this post in threaded view
|

Re: How to improve the docs?

Frank Brückner
Hello Justin,
I think this is the wrong way, because we do not need a new infrastructure for the docs. We need content! We need fully described components, more code examples and we need explanations how to integrate a component in a MVC application.
 
Yes, we need more consistency between the description of components (outline).
Yes, we need a better navigation.
Yes, we must use the syntax for functions. (Example: http://goo.gl/0mwTX)
...
But we do not need a new documentation format, because that does not bring any new or better content!
 
My two cents.
 
 
Kind regards,
Frank
Justin Martin <[hidden email]> hat am 26. Juni 2013 um 20:48 geschrieben:

On 13-06-26 03:30 AM, Andreas Möller wrote:
Maybe it's really the best idea to improve the documentation *within*
the code. Then the documentation would be as close to the code as
possible and it would be a lot easier to review PRs both in terms of
documentation and code provided.
This is what I wrote about a month ago to this mailing list and it got
quite unnoticed. This is the best way to document separated components.
How should we get along with tackling this, everyone? 

I think the most important thing to find out beforehand is

* How can we parse the API documentation to generate a nice looking documentation from it?

When that question is answered, I guess we should just go ahead and update the existing API documentation.


Best regards,

Andreas

My suggestion would really be contingent upon some major changes to the structure of the documentation.

Gary and I had an outside conversation about basically starting a new, formalized documentation process which would make some major changes to how the documentation is handled.

First and foremost, I would like to see a change in the *format* of the documentation. By no means would I suggest scrapping RST, but what I would like to see is a move to a hybrid of Docbook and RST.
The reasons for this are plentiful, but first and foremost it is because RST is not a semantic documentation format. The chief issue with the current documentation is that it lacks clear and concise API documentation.
This is largely because RST offers no standard that I'm aware of for semantic definition of class/method/function information. I'm sure some skeleton for that could be hacked together, but it's really just overextending the usefulness of the format.

If you were to take a look at, say, http://svn.php.net/viewvc/phpdoc/en/trunk/reference/pdo/pdostatement/fetchall.xml?view=markup#l12, you can see how usefully semantic Docbook is.

This being said, I do *understand* why RST was picked for the documentation that ZF2 *does* have. It offers a simple format for "stream of consciousness" documentation that is simply not possible with Docbook. Writing Docbook markup requires a fair bit of foreknowledge, which acts as a substantial barrier to entry for new documentation contributors.

So, what I would recommend doing is creating a hybrid format for the documentation which makes use of Docbook for the semantic documentation of class structures, method calls and property/parameter information. Then, for examples, which the current documentation is basically a mash of, use RST in separate files which are then linked into the semantic documentation, in a format similar to how PHP's manual does it.

When a get some time, I'll see about putting together a proof of concept for one of the components in the framework (say, Stdlib), to demonstrate what I'm talking about, since documentation formats can be a bit esoteric.

Thanks,
Justin Martin

 
Reply | Threaded
Open this post in threaded view
|

Re: How to improve the docs?

resourcemode
This post has NOT been accepted by the mailing list yet.
Below link have a very good point on how to improve the documentation.
http://zend-framework-community.634137.n4.nabble.com/Documentation-Part-td4660459.html

Michael Favila
Singapore
12