http://www.reddit.com/r/programming/comments/19npsp/developers_may_be_getting_as_much_as_50_of_their/

What I get from this is that people really like PHP's documentation style where users can add to it.

On Wednesday, 6 March 2013 at 08:17:58 UTC, Walter Bright wrote:
> http://www.reddit.com/r/programming/comments/19npsp/developers_may_be_getting_as_much_as_50_of_their/
>
> What I get from this is that people really like PHP's documentation style where users can add to it.

Stackoverflow is very good when it comes to specific questions. With the PHP documentation it sometimes takes a while until I find an example of what I need to do. I think a very good way is to include examples in the documentation where it makes sense. The Cocoa documentation does that and also the D Library Reference. I like the "Synopsis" part.

On Wednesday, 6 March 2013 at 08:17:58 UTC, Walter Bright wrote:
> What I get from this is that people really like PHP's documentation style where users can add to it.

Of course, plus the rank system, (where the best answers appears first), you "almost" have a winner.

I said "almost", because I've seen answers that were classified ("despite working") above other better or optmized answers because of the date they were posted.

IMHO maybe in programming side, it would be nice to have an additional technical vote walking together with rank system.

On Wed, Mar 06, 2013 at 12:05:18PM +0100, Chris wrote:
> On Wednesday, 6 March 2013 at 08:17:58 UTC, Walter Bright wrote:
> >http://www.reddit.com/r/programming/comments/19npsp/developers_may_be_getting_as_much_as_50_of_their/
> >
> >What I get from this is that people really like PHP's documentation style where users can add to it.
> 
> Stackoverflow is very good when it comes to specific questions. With the PHP documentation it sometimes takes a while until I find an example of what I need to do. I think a very good way is to include examples in the documentation where it makes sense. The Cocoa documentation does that and also the D Library Reference. I like the "Synopsis" part.

Yeah, we need to go through existing (non-deprecated) Phobos modules and write up synopses for each of them. Too many Phobos modules still don't have a good overview that tells you what the module is useful for and what are the most common/important functions/structs/classes/etc.. Examples are also sorely lacking.

Another thing I find frustrating with Phobos docs is the lack of navigability. A large module can easily have 30-50 functions, and putting detailed docs for each one on a single page is a bad idea. I think somebody did up a version with improved navigation -- any chance of that becoming the official Phobos docs anytime soon?


T

-- 
Bomb technician: If I'm running, try to keep up.

On Wednesday, 6 March 2013 at 19:58:36 UTC, H. S. Teoh wrote:
> Another thing I find frustrating with Phobos docs is the lack of
> navigability. A large module can easily have 30-50 functions, and
> putting detailed docs for each one on a single page is a bad idea. I
> think somebody did up a version with improved navigation -- any chance
> of that becoming the official Phobos docs anytime soon?
>
>
> T

Sönke Ludwig made ddox which does this.

Phobos example: http://vibed.org/temp/d-programming-language.org/phobos/index.html
Pull request: https://github.com/D-Programming-Language/d-programming-language.org/pull/267

On Wednesday, 6 March 2013 at 21:11:36 UTC, Brad Anderson wrote:
> Sönke Ludwig made ddox which does this.
>
> Phobos example: http://vibed.org/temp/d-programming-language.org/phobos/index.html
> Pull request: https://github.com/D-Programming-Language/d-programming-language.org/pull/267

bootDoc also provides navigation, using a sidebar:

http://jakobovrum.github.com/bootdoc-phobos/

It doesn't automatically generate an index page or strip the manual attempts at providing navigation throughout Phobos, so bootDoc is much more suited for custom projects without this cruft:

http://jakobovrum.github.com/LuaD/

It's still limited by DDoc though, everything is static and done using JavaScript...

On Wednesday, 6 March 2013 at 08:17:58 UTC, Walter Bright wrote:
> http://www.reddit.com/r/programming/comments/19npsp/developers_may_be_getting_as_much_as_50_of_their/
>
> What I get from this is that people really like PHP's documentation style where users can add to it.

For what it's worth, MSDN has something like that, too, but without a voting system.

On Wednesday, 6 March 2013 at 08:17:58 UTC, Walter Bright wrote:
> http://www.reddit.com/r/programming/comments/19npsp/developers_may_be_getting_as_much_as_50_of_their/
>
> What I get from this is that people really like PHP's documentation style where users can add to it.

I notice in the their developer page visits, developer Q (mostly official doc user) seems to have much more time to check his email :)