The kind of documentation people like

[H. S. Teoh]

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.