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 "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
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 "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
prev sibling next sibling parent "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
prev sibling next sibling 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 "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