www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - The kind of documentation people like

reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Mar 06 2013
next sibling parent reply "Chris" <wendlec tcd.ie> writes:
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.
Mar 06 2013
parent reply "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
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.
Mar 06 2013
parent reply "Brad Anderson" <eco gnuk.net> writes:
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
Mar 06 2013
parent "Jakob Ovrum" <jakobovrum gmail.com> writes:
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...
Mar 06 2013
prev sibling next sibling parent "MattCodr" <mattcodr hotmail.com> writes:
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.
Mar 06 2013
prev sibling next sibling parent "Denis Koroskin" <2korden gmail.com> writes:
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.
Mar 06 2013
prev sibling parent "Jesse Phillips" <Jesse.K.Phillips+D gmail.com> writes:
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 :)
Mar 06 2013