www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Can we get a forum section devoted to documentation?

reply "Andre Artus" <andre.artus gmail.com> writes:
I would like to contribute to the D ecosystem, but as I'm still 
in the learning process I do not want to get my sticky fingers 
all over someones nice clean code.

I have poured over the documentation and see that there are a few 
low-hanging fruit that I would like to pluck. So I have decided 
to do so.

I would like for there to be a section were people interested in 
working on the docs can collaborate.
Aug 16 2013
next sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
 I would like to contribute to the D ecosystem, but as I'm still 
 in the learning process I do not want to get my sticky fingers 
 all over someones nice clean code.

 I have poured over the documentation and see that there are a 
 few low-hanging fruit that I would like to pluck. So I have 
 decided to do so.

 I would like for there to be a section were people interested 
 in working on the docs can collaborate.

I like this idea. Currently improving the docs is often blocked by the fact that only very few people for every different topic exist who know exactly what is the intended and proper behavior to be documented. And you mostly get that information only in some random bugzilla reports. Having a common place to discuss it can be a good foundation towards solid formal spec.
Aug 16 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 8/16/13 9:22 AM, Dicebot wrote:
 On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
 I would like to contribute to the D ecosystem, but as I'm still in the
 learning process I do not want to get my sticky fingers all over
 someones nice clean code.

 I have poured over the documentation and see that there are a few
 low-hanging fruit that I would like to pluck. So I have decided to do so.

 I would like for there to be a section were people interested in
 working on the docs can collaborate.

I like this idea. Currently improving the docs is often blocked by the fact that only very few people for every different topic exist who know exactly what is the intended and proper behavior to be documented. And you mostly get that information only in some random bugzilla reports. Having a common place to discuss it can be a good foundation towards solid formal spec.

Just use this forum and plant e.g. [dox] in the title. Andrei
Aug 16 2013
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 8/16/13 10:12 AM, Dicebot wrote:
 On Friday, 16 August 2013 at 16:36:16 UTC, Andrei Alexandrescu wrote:
 Just use this forum and plant e.g. [dox] in the title.

 Andrei

Why prefer less structured and inconvenient approach to an organized one? :) digitalmars.D is not that quite these days and discussing formal spec definitions sounds like an important goal, worth dedicated forum block.

The converse risk is balkanization. We already have subgroups that are effectively dead, for which similar arguments were made in the past. Andrei
Aug 16 2013
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 8/16/13 10:56 AM, Dicebot wrote:
 On Friday, 16 August 2013 at 17:41:19 UTC, Andrei Alexandrescu wrote:
 The converse risk is balkanization. We already have subgroups that are
 effectively dead, for which similar arguments were made in the past.

Problem with current subgroups is that they are created on topic basis, not to solve some specific problems. Such groups become useless once person who is the driving force behind the relevant project stops using it. I'd probably favor deleting such obsolete groups (dtl, dwt, debugger?) but it is a different topic. Documentation group has clear target audience (newcomers with questions/proposals about the spec + ones willing to contribute to dlang.org) and very specific problem to solve (most non-trivial documentation changes are impossible without prior discussion).

The argument is built from a mistaken angle. "Thinking of doing some work on docs in the future, let's create a group for docs!" Things should happen organically, i.e. creating a specialized group should follow a need substantiated by increased volume of specialized discussion in the general group. At this point there is nothing in that vein. Andrei
Aug 16 2013
prev sibling next sibling parent "Mr. Anonymous" <mailnew4ster gmail.com> writes:
On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
 I would like to contribute to the D ecosystem, but as I'm still 
 in the learning process I do not want to get my sticky fingers 
 all over someones nice clean code.

 I have poured over the documentation and see that there are a 
 few low-hanging fruit that I would like to pluck. So I have 
 decided to do so.

 I would like for there to be a section were people interested 
 in working on the docs can collaborate.

Related: http://forum.dlang.org/post/bxqyiyohbodlxypxgjal forum.dlang.org
Aug 16 2013
prev sibling next sibling parent "Craig Dillabaugh" <cdillaba cg.scs.carleton.ca> writes:
On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
 I would like to contribute to the D ecosystem, but as I'm still 
 in the learning process I do not want to get my sticky fingers 
 all over someones nice clean code.

 I have poured over the documentation and see that there are a 
 few low-hanging fruit that I would like to pluck. So I have 
 decided to do so.

 I would like for there to be a section were people interested 
 in working on the docs can collaborate.

It is pretty easy to make minor corrections to the documentation through the GitHub repo. I made such a correction myself to a glaring documentation error recently. My first ever open source contribution, but hopefully many more to come in the future. I often thought, like yourself, that improving the D documentation would be a good way to contribute. Having a forum to vet ideas would be very nice. I find the D documentation is sorely lacking in example code, and high level descriptions of modules (thinking more of Phobos here) and having a forum to say "Here is some 'description/example code' I want to add to the Phobos docs", would be a good way for less experienced developers to start contributing. Such a forum would be a good way to get some feedback before getting to the point of pushing your changes to the Repo.
Aug 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Aug 16, 2013 at 06:29:40PM +0200, Craig Dillabaugh wrote:
 On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
I would like to contribute to the D ecosystem, but as I'm still in
the learning process I do not want to get my sticky fingers all
over someones nice clean code.

I have poured over the documentation and see that there are a few
low-hanging fruit that I would like to pluck. So I have decided to
do so.


+1.
I would like for there to be a section were people interested in
working on the docs can collaborate.


+1. I would subscribe to that.
 It is pretty easy to make minor corrections to the documentation
 through the GitHub repo. I made such a correction myself to a
 glaring documentation error recently.  My first ever open source
 contribution, but hopefully many more to come in the future.  I
 often thought, like yourself, that improving the D documentation
 would be a good way to contribute.  Having a forum to vet ideas
 would be very nice.

We badly, badly, need people to work on the documentation. One of the major complaints I heard from a friend about D is that the docs are very poor. Coders tend to be very bad at writing docs, because we understand our own code too well -- our perception is unconsciously colored by hidden assumptions that newbies don't know about, which makes the docs hard to understand. Writing docs for others' code is better, though. :)
 I find the D documentation is sorely lacking in example code,

+1. I think *every* Phobos function needs at least one code example, at least in principle. It may sound redundant to experienced D coders, but such redundancy is very important for somebody who's learning the language for the first time.
 and high level descriptions of modules (thinking more of Phobos here)

Most Phobos modules suffer from this problem. The first paragraph often just says something to the effect of "this is module X (we already know that) and it contains Y, Z, W (we can see that already)". Very unhelpful. We need descriptions of: 1) What: what this module does -- from the high-level view. 2) Why: why do we need this module in the first place? why should we care? 3) When: when this module might be useful. Give some example applications that might benefit from this module. 4) How: example code to demonstrate how this module can help you in your code. 5) Where: overview of module contents (or, where to find stuff). A lot of Phobos docs currently just dump a long unnavigable list of symbols declared, with no high-level organization of them. This makes it nigh impossible to find what you're looking for unless you already know where it is. We should at least group things into logical sections / categories, and put these categories near the top where it's easier to find what you're looking for (std.range, while not perfect, is a good example of how this can help navigate the module).
 and having a forum to say "Here is some 'description/example code' I
 want to add to the Phobos docs", would be a good way for less
 experienced developers to start contributing. Such a forum would be a
 good way to get some feedback before getting to the point of pushing
 your changes to the Repo.

+1. You can also just submit pull requests to update the docs; it's a good way to get feedback from the core Phobos devs. A large number of Phobos modules badly need a documentation facelift. I've tried to improve std.range before -- I can't say it's perfect but it's certainly a lot better than what it used to be. But too many Phobos modules aren't even at that level yet. We really need to fix that if we want wider adoption of D. Also needed is somebody to read through related parts of the docs, and catch contradictory parts (e.g., the terminology confusion between http://dlang.org/tuple.html, http://dlang.org/phobos/std_typecons.html, and http://dlang.org/phobos/std_typetuple.html). In any case, I think I talk too much about it. Let's get the documentation pull requests going!! And start the docs discussion group. T -- The early bird gets the worm. Moral: ewww...
Aug 16 2013
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Friday, 16 August 2013 at 16:36:16 UTC, Andrei Alexandrescu 
wrote:
 Just use this forum and plant e.g. [dox] in the title.

 Andrei

Why prefer less structured and inconvenient approach to an organized one? :) digitalmars.D is not that quite these days and discussing formal spec definitions sounds like an important goal, worth dedicated forum block.
Aug 16 2013
prev sibling next sibling parent "Wyatt" <wyatt.epp gmail.com> writes:
On Friday, 16 August 2013 at 16:53:47 UTC, H. S. Teoh wrote:
 +1.

s/\+1/\+2/ to everything. Might encourage me to get back to my own doc stuff. -Wyatt
Aug 16 2013
prev sibling next sibling parent "Suliman" <evermind live.ru> writes:
On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
 I would like to contribute to the D ecosystem, but as I'm still 
 in the learning process I do not want to get my sticky fingers 
 all over someones nice clean code.

 I have poured over the documentation and see that there are a 
 few low-hanging fruit that I would like to pluck. So I have 
 decided to do so.

 I would like for there to be a section were people interested 
 in working on the docs can collaborate.

It would be perfect to get D version of http://www.dotnetperls.com/
Aug 16 2013
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Friday, 16 August 2013 at 17:41:19 UTC, Andrei Alexandrescu 
wrote:
 The converse risk is balkanization. We already have subgroups 
 that are effectively dead, for which similar arguments were 
 made in the past.

Problem with current subgroups is that they are created on topic basis, not to solve some specific problems. Such groups become useless once person who is the driving force behind the relevant project stops using it. I'd probably favor deleting such obsolete groups (dtl, dwt, debugger?) but it is a different topic. Documentation group has clear target audience (newcomers with questions/proposals about the spec + ones willing to contribute to dlang.org) and very specific problem to solve (most non-trivial documentation changes are impossible without prior discussion). In that sense I think bugzilla is a more appropriate place for such discussions but it is not as visible and newbie-friendly as forum group.
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
 H. S. Teoh wrote:
 Most Phobos modules suffer from this problem. The first 
 paragraph often just says something to the effect of "this is 
 module X (we already know that) and it contains Y, Z, W (we can 
 see that already)". Very unhelpful. We need descriptions of:
 
 1) What: what this module does -- from the high-level view.
 
 2) Why: why do we need this module in the first place? why 
 should we care?
 
 3) When: when this module might be useful. Give some example 
 applications that might benefit from this module.
 
 4) How: example code to demonstrate how this module can help 
 you in your code.
 
 5) Where: overview of module contents (or, where to find 
 stuff). A lot of Phobos docs currently just dump a long 
 unnavigable list of symbols declared, with no high-level 
 organization of them. This makes it nigh impossible to find 
 what you're looking for unless you already know where it is. We 
 should at least group things into logical sections / 
 categories, and put these categories near the top where it's 
 easier to find what you're looking for (std.range, while not 
 perfect, is a good example of how this can help navigate the 
 module).
 

These are all excellent suggestions. I believe that adopting this approach would improve the usability immensely. Is there a way to break the pages into a more of a hierarchy, so that documentation for each module doesn't have to be on one page? Perhaps a DDOC Section could indicate the category? Getting into working on the documentation seems to not be as easy as it ought to be. I am talking about the macro system, which is easy enough to grok once you have seen enough examples of it, but there is a shortage of guidance for the noob. I think a good place to start is with the creation of a README file on GitHub. This file should at the very least: - Explain how the documentation source is organized, i.e. dependency on Phobos, etc. - What the different make targets are, and * what tools are required to build each target, * a link to where to find each tool - Point to a page explaining a little about DDOC. - What the vetting process is - Where to discuss or propose ideas for additions or changes - A link to content guidelines based on what H. S. Teoh listed above.
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 18:09:04 UTC, Andrei Alexandrescu 
wrote:
 On 8/16/13 10:56 AM, Dicebot wrote:
 On Friday, 16 August 2013 at 17:41:19 UTC, Andrei Alexandrescu 
 wrote:
 The converse risk is balkanization. We already have subgroups 
 that are
 effectively dead, for which similar arguments were made in 
 the past.

Problem with current subgroups is that they are created on topic basis, not to solve some specific problems. Such groups become useless once person who is the driving force behind the relevant project stops using it. I'd probably favor deleting such obsolete groups (dtl, dwt, debugger?) but it is a different topic. Documentation group has clear target audience (newcomers with questions/proposals about the spec + ones willing to contribute to dlang.org) and very specific problem to solve (most non-trivial documentation changes are impossible without prior discussion).

The argument is built from a mistaken angle. "Thinking of doing some work on docs in the future, let's create a group for docs!" Things should happen organically, i.e. creating a specialized group should follow a need substantiated by increased volume of specialized discussion in the general group. At this point there is nothing in that vein. Andrei

I understand were you are coming from. And, while I currently feel that it's a bit of a catch-22 situation, I think it is worth at least trying out your suggestion of marking document related threads with "[dox]".
Aug 16 2013
prev sibling next sibling parent "Dicebot" <public dicebot.lv> writes:
On Friday, 16 August 2013 at 18:09:04 UTC, Andrei Alexandrescu 
wrote:
 The argument is built from a mistaken angle. "Thinking of doing 
 some work on docs in the future, let's create a group for docs!"

 Things should happen organically, i.e. creating a specialized 
 group should follow a need substantiated by increased volume of 
 specialized discussion in the general group. At this point 
 there is nothing in that vein.

That is a good point.
Aug 16 2013
prev sibling next sibling parent "Wyatt" <wyatt.epp gmail.com> writes:
 On 8/16/13 10:56 AM, Dicebot wrote:
 it. I'd probably favor deleting such obsolete groups (dtl, 
 dwt, debugger?) but it is a different topic.



On Friday, 16 August 2013 at 18:25:02 UTC, Andre Artus wrote:
 I understand were you are coming from. And, while I currently 
 feel that it's a bit of a catch-22 situation, I think it is 
 worth at least trying out your suggestion of marking document 
 related threads with "[dox]".

For the future, the convention of most mailing lists I've seen is to put the braced tag at the front so you know what it's about immediately. :) -Wyatt
Aug 16 2013
prev sibling next sibling parent "Mr. Anonymous" <mailnew4ster gmail.com> writes:
On Friday, 16 August 2013 at 18:12:57 UTC, Andre Artus wrote:
 Is there a way to break the pages into a more of a hierarchy, 
 so that documentation for each module doesn't have to be on one 
 page? Perhaps a DDOC Section could indicate the category?

Are you familiar with DDOX? http://vibed.org/temp/d-programming-language.org/phobos/index.html
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 19:12:46 UTC, Mr. Anonymous wrote:
 On Friday, 16 August 2013 at 18:12:57 UTC, Andre Artus wrote:
 Is there a way to break the pages into a more of a hierarchy, 
 so that documentation for each module doesn't have to be on 
 one page? Perhaps a DDOC Section could indicate the category?

Are you familiar with DDOX? http://vibed.org/temp/d-programming-language.org/phobos/index.html

I have not yet had the time to look into it, but I fear that it would be of little use if it's not the official way of doing docs. Although it may be the preferred option for private projects or projects not directly connected to the main D ecosystem. There is already quite a lot of fragmentation making it quite an effort to find out what the "one true path"[1] is. 1. I realize that there isn't truly such a thing, but an opinionated starting point is of great help to noobs. The major feature to popularize Ruby on Rails when it first kicked off was, in my opinion, the "on rails" part. You had a very clear indication of where to start, and what the best/accepted/expected practices are. Once you have accustomed yourself to the language and framework you can find ways to go crashing through the bushes if you feel the need to do so.
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 18:41:57 UTC, Wyatt wrote:
 On 8/16/13 10:56 AM, Dicebot wrote:
 it. I'd probably favor deleting such obsolete groups (dtl, 
 dwt, debugger?) but it is a different topic.



On Friday, 16 August 2013 at 18:25:02 UTC, Andre Artus wrote:
 I understand were you are coming from. And, while I currently 
 feel that it's a bit of a catch-22 situation, I think it is 
 worth at least trying out your suggestion of marking document 
 related threads with "[dox]".

For the future, the convention of most mailing lists I've seen is to put the braced tag at the front so you know what it's about immediately. :) -Wyatt

Duly noted. I have done so in my subsequent posts (which are waiting for comments, hint, hint)
Aug 16 2013
prev sibling next sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Friday, August 16, 2013 10:41:19 Andrei Alexandrescu wrote:
 The converse risk is balkanization. We already have subgroups that are
 effectively dead, for which similar arguments were made in the past.

Plus, if one of the main complaints with regards to the documentation is that only a few people know the correct behavior for each of the various items which need to be documented, splitting off into your own group where those people probably won't even be isn't very helpful. - Jonathan M Davis
Aug 16 2013
prev sibling next sibling parent "Mr. Anonymous" <mailnew4ster gmail.com> writes:
On Friday, 16 August 2013 at 19:27:58 UTC, Andre Artus wrote:
 On Friday, 16 August 2013 at 19:12:46 UTC, Mr. Anonymous wrote:
 On Friday, 16 August 2013 at 18:12:57 UTC, Andre Artus wrote:
 Is there a way to break the pages into a more of a hierarchy, 
 so that documentation for each module doesn't have to be on 
 one page? Perhaps a DDOC Section could indicate the category?

Are you familiar with DDOX? http://vibed.org/temp/d-programming-language.org/phobos/index.html

I have not yet had the time to look into it, but I fear that it would be of little use if it's not the official way of doing docs. Although it may be the preferred option for private projects or projects not directly connected to the main D ecosystem. There is already quite a lot of fragmentation making it quite an effort to find out what the "one true path"[1] is. 1. I realize that there isn't truly such a thing, but an opinionated starting point is of great help to noobs. The major feature to popularize Ruby on Rails when it first kicked off was, in my opinion, the "on rails" part. You had a very clear indication of where to start, and what the best/accepted/expected practices are. Once you have accustomed yourself to the language and framework you can find ways to go crashing through the bushes if you feel the need to do so.

It's planned as the official way of doing docs. There are pull request for it, but it's going nowhere for the past several months. A related thread: http://forum.dlang.org/thread/dsnpggjmndaxiusfqhjk forum.dlang.org
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 19:29:46 UTC, Jonathan M Davis wrote:
 On Friday, August 16, 2013 10:41:19 Andrei Alexandrescu wrote:
 The converse risk is balkanization. We already have subgroups 
 that are
 effectively dead, for which similar arguments were made in the 
 past.

Plus, if one of the main complaints with regards to the documentation is that only a few people know the correct behavior for each of the various items which need to be documented, splitting off into your own group where those people probably won't even be isn't very helpful. - Jonathan M Davis

It is disheartening to think that the people with potential for the most valuable contributions or insight will be avoiding discussions regarding the documentation. But I fear you are correct. I have admittedly not been around here for long, but haven't seen too many discussions focused on documentation (other than to bemoan/defend DDOC, which in itself seems not to do much towards improving the actual documentation). I have proposed a changes to the documentation before but it's obviously less interesting than the optimal way to decelerate an automobile. English is not my mother tongue, and I am not always confident that I have expressed myself in the manner I intended. It's difficult to make sure that one does not just directly translate idiomatic expressions from your mother tongue that don't make sense to others. I'm happy to follow the convention proposed by Andrei. Although I fear it lacks discoverability for newcomers. Perhaps over time we can build enough interest in the documentation to warrant a more focused approach.
Aug 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Aug 16, 2013 at 08:25:00PM +0200, Andre Artus wrote:
 On Friday, 16 August 2013 at 18:09:04 UTC, Andrei Alexandrescu
 wrote:

Things should happen organically, i.e. creating a specialized
group should follow a need substantiated by increased volume of
specialized discussion in the general group. At this point there
is nothing in that vein.


 I understand were you are coming from. And, while I currently feel
 that it's a bit of a catch-22 situation, I think it is worth at
 least trying out your suggestion of marking document related threads
 with "[dox]".

Alright, I'll start. Here's a list of Phobos modules that need some documentation facelist. For fairness' sake, I gleaned these from: http://dlang.org/phobos-prerelease/index.html as opposed to the docs for the official release, so that they closer reflect what things will look like at the next D release. 1) The above page itself needs work. Right now it's just a very spotty incomplete list of seemingly-random pieces of Phobos. It looks like the relic from a bygone era before Phobos docs had a navbar on the left; so my first thought would be to kill off that incomplete module list (leave that to the navbar). My second thought would be to group the modules under more logical categories so that newbies would know which modules tend to be used together (e.g., std.algorithm and std.range tend to be used together a lot IME). 2) std.algorithm: the state of the current docs is not bad, but could use some improvement. The first paragraph could be expanded to explain what this module is all about. The part about string lambdas (2nd paragraph) may need to be tagged with a note about possible deprecation, judging from discussions in the other thread. If not, at the very least the code example should show how to use the new lambda syntax: sort!((a,b) => a < b)(...); I'm not sure what to make of the cheat sheet, as it seems to repeat most of the table of links at the top of the page. But maybe it's good for short code snippets to remind you how to use each function, so maybe it can be left alone for now. 3) std.array: desperately needs a more detailed explanation at the top to explain why this module is even needed (newbies would wonder: doesn't D have built-in arrays? Why do we need this module then?). Not enough code examples. 4) std.ascii: unhelpful description. Why do we even need this module when D uses UTF-8 by default? When should we use this module and when should we use std.uni? Also, needs an overview of what this module provides (string constants, character categorization, case conversions). 5) std.base64: unhelpful description. Doesn't explain what is base-64 and why we should care. What are the applications of base-64 anyway? Who would want to use this stuff? Without more details, a newcomer wouldn't know. 6) std.bigint: badly needs more code examples, with explanations. 7) std.bitmanip: needs more explanation about what this module is, why we need it, etc.. Needs categorization of what is provided (bitfields, endianness-related functions, anything else). 8) std.compiler: need code examples of how to use the stuff here. Maybe using version blocks. Maybe sample music composed in D_major... oh wait. Wrong forum. :-P 9) std.complex: needs more code examples. Maybe a little more explanation about what's going on with "built-in types" and why those will be replaced. 10) std.concurrency: needs higher-level module description, like what's the use of low-level messaging systems. Need to provide adequate context for where/when this module should be used. Needs to link to other doc pages that discuss threads, processes, etc.. 11) std.container: badly needs a better description. The table of operations with complexity guarantees needs a bit more explanation about what this all means. Maybe a link to somewhere (wikipedia perhaps) that explains the concept of complexity and why it matters. Also, need an overview of what containers are provided and example code on how to use them. 12) std.conv: the one-line description is cute, but inadequate. Need code examples on common usage. Need to explain in more detail how to make user-defined types usable with to!() (e.g., need to define opCast, ctor requirements, etc.). Need module overview about what's provided (to, octal, parse, emplace). Need code examples. 13) std.csv: Not bad, but could use an overview of module contents with links to each main function/struct (ala std.algorithm / std.range). 14) std.datetime: Not bad. It would be nice to add links to actual functions/types in the module overview. 15) std.encoding: needs more code examples. Overview of module contents. 16) std.exception: needs higher-level overview of what's in this module, with categorized functions/types. Code examples for assertThrown & co., as well as explanations of why we need them. 17) std.file: needs more code examples. Module contents overview. 18) std.format: there are a lot of good docs here, but buried in hard-to-find places. Needs module overview, with code examples. There also appear to be some DDOC typos here. Especially needed is: how to make your own user-defined types usable with std.format. What are the possible hooks, example code of how they are used, etc.. 19) std.functional: need more explanation of what this module is all about. Motivation: why do we care about functions manipulating other functions? There are some code examples here but could use better motivated examples, like when/where such features would be useful. How this relates to functional programming, etc.. 20) std.getopt: not bad. Maybe add some examples of an actual shell session and how getopt parses things. Explain what args[0] means (this is very non-obvious to people unfamiliar with command-line UIs!). 21) std.json: needs proper description and code examples. 22) std.math: needs categorized summary of module contents. 23) std.mathspecial: needs code examples. Explanation of why this isn't part of std.math. 24) std.mmfile: needs a LOT of explanation of what this is, and why it might be useful. Code examples. 25) std.numeric: needs adequate explanation of what this module does and why it's needed. Why isn't it part of std.math, what's the difference, etc.. Categorized summary of module contents. 26) std.outbuffer: needs explanation of what this module is. Code examples. 27) std.parallelism: not bad. A linked overview of module contents would be nice. 28) std.path: needs linked overview of module contents. Why this isn't part of std.file. In fact, the Phobos index page should group std.file, std.stdio, and std.path together, and explain what's the difference between them, and what each module covers in terms of file-related operations. 29) std.process: pretty good! Maybe explain how this relates to std.parallelism, std.concurrency, etc.. The difference may not be obvious to newcomers. Possibly put this explanation in the Phobos index page. 30) std.random: linked overview of module contents would be nice. More code examples. Maybe a brief discussion on various RNG issues, like measure of randomness, reproducible/non-reproducible sequences, cryptographic strength, etc.. 31) std.range: not bad (if I say so myself ;-P). More code examples would be nice. As well as motivating examples of when you might want to use each range type. 32) std.regex: pretty good! 33) std.signals: ugly. The links to various forum discussion threads is a poor substitute for a well-written summary of the contents of said discussions. Needs more code examples and applications. 34) std.socket: needs a module description!! And many more code examples. And module contents overview. 35) std.socketstream: not sure if we want to spend more effort documenting this, since it's slated for replacement, but might not hurt in the short term to do so. 36) std.stdio: very unhelpful description. Should explain exactly what this module does for people who *don't* know C, what types / functions it exports, code examples of how to use them. E.g., how to open / close a file, how to read/write text data, how to read/write binary data. Explain range interface for files. Caveats on the transience of byLine. 37) std.cstream, std.stream: not sure how much to do for these, since they're slated for replacement. 38) std.string: need better description. Why this module exists (aren't strings built-in in D?), what it provides (linked overview of contents), more code examples. 39) std.system: explain what this module is, why we need it, when it should be used. Code examples (*motivating* code examples, not just random code snippets that happens to use the symbols exported here!). This should be grouped with std.compiler in the Phobos index page. 40) std.traits: need to elaborate on description. Brief discussion of metaprogramming maybe? With motivating code examples. Need linked overview of contents. There's a lot of stuff in here; grouping into logical categories should be more helpful. 41) std.typecons: need better description. Explain basic usage, what it means, etc.. The current code example is rather abstruse to a newcomer; needs more down-to-earth explanations of what exactly is going on in the code. Needs overview of contents. More code examples. Things like Flag should be highlighted so that newbies pick up on the concept and use Flag instead of bools everywhere. 42) std.typetuple: need proper explanation of the difference between TypeTuple, std.range.Tuple, and compile-time "tuples" (SymbolTuples, as Ali calls them). This is very confusing for newbies (and even for experienced D coders!). Overview of module contents. 43) std.uni: I think Dmitry's new std.uni hasn't been updated on dlang.org yet, so I'll refrain from commenting for now. From what I remember, the new docs (and code, of course!) are far better than the one you see on dlang.org, so probably we don't have to worry about it. 44) std.uri: the description could use some elaboration. And code examples. 45) std.utf: need to elaborate description. How this relates to std.uni. Example code. Issues to deal with when interfacing with C code (toUTF*z). 46) std.uuid: not bad! 47) std.variant: not bad. Could use more code examples in a few places. Maybe higher-level discussion of usage, motivation, potential issues, etc.. Overview of module contents. 48) std.xml: slated for replacement; so just let be for now? 49) std.zip: Need better module description, overview of contents. How this relates to std.zlib. 50) std.zlib: why this isn't part of std.zip. Code examples!! 51) std.net.curl: not bad. 52) std.net.isemail: need code examples! 53) std.digest.*: not bad! Phobos index page needs to group these together and explain how each piece relates to the others. 54) std.windows.charset: explain why this isn't part of std.encoding. Code examples. (Also, why is the CSS broken for this page on dlang.org?) Phew, I never realized Phobos was *this* big! This covers only std.*, but there's still etc.* and core.*. Lots of work ahead of us! T -- Your inconsistency is the only consistent thing about you! -- KD
Aug 16 2013
prev sibling next sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Friday, August 16, 2013 21:57:01 Andre Artus wrote:
 It is disheartening to think that the people with potential for
 the most valuable contributions or insight will be avoiding
 discussions regarding the documentation. But I fear you are
 correct.

There's a difference between avoiding discussions and searching after them. If a discussion occurs in a list that they're already subscribed to, they're a lot more likely to read it and contribute to it than they are to go and subscribe to yet another list. - Jonathan M Davis
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 17:45:35 UTC, Suliman wrote:
 On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
 I would like to contribute to the D ecosystem, but as I'm 
 still in the learning process I do not want to get my sticky 
 fingers all over someones nice clean code.

 I have poured over the documentation and see that there are a 
 few low-hanging fruit that I would like to pluck. So I have 
 decided to do so.

 I would like for there to be a section were people interested 
 in working on the docs can collaborate.

It would be perfect to get D version of http://www.dotnetperls.com/

That's pretty cool. It would be good to have something like that for D, or a "Ninety-Nine D Problems", or a Try-D, or an update to http://en.wikibooks.org/wiki/D. I'm wiling to work towards those goals. There are a number of good articles and other D materials strewn around the web, perhaps we can find place to include or link to them from dlang.org.
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 20:12:20 UTC, Jonathan M Davis wrote:
 On Friday, August 16, 2013 21:57:01 Andre Artus wrote:
 It is disheartening to think that the people with potential for
 the most valuable contributions or insight will be avoiding
 discussions regarding the documentation. But I fear you are
 correct.

There's a difference between avoiding discussions and searching after them. If a discussion occurs in a list that they're already subscribed to, they're a lot more likely to read it and contribute to it than they are to go and subscribe to yet another list. - Jonathan M Davis

I am using the web interface to the forums, so I must admit I did not think how other users may need to jump through additional hoops. I was thinking about it in the fashion of how web-based forums normally operate, were a separate section could advance discoverability, but I can see how this can be counterproductive given a significant number of email only users.
Aug 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Aug 16, 2013 at 04:12:11PM -0400, Jonathan M Davis wrote:
 On Friday, August 16, 2013 21:57:01 Andre Artus wrote:
 It is disheartening to think that the people with potential for
 the most valuable contributions or insight will be avoiding
 discussions regarding the documentation. But I fear you are
 correct.

There's a difference between avoiding discussions and searching after them. If a discussion occurs in a list that they're already subscribed to, they're a lot more likely to read it and contribute to it than they are to go and subscribe to yet another list.

Good point. Though I have to say, actually reading Phobos code to figure out what it does is actually much less scary than it sounds. It's orders of magnitude better than, say, reading the source code of Glibc. Thanks to D's superior syntax and other readability features, Phobos code actually reads like "normal" application code for the most part. It's not that hard to understand at all. I can't say the same for things like Glibc (or ncurses -- I tried reading that once and my eyes bled). And when that fails (there are some places where it isn't obvious what the code is doing), there's always the copy-paste-modify method: copy Phobos code into a temporary file, wrap a main() around it, and run it yourself to see what it does. Again thanks to D's readability and modularity features, for the most part this will actually work painlessly. In fact, you can even copy, say, std.algorithm.find into /tmp/test.d, then import std.algorithm at the top so that any subfunctions or subtemplates that it calls will automatically resolve back to the Phobos code, but when main() calls find(), your copy of find() gets used instead because the local module gets higher preference when resolving overloads. Then you can modify your copy of find() to your heart's content and observe what it does, etc.. Man I love D... Try doing that with glibc or ncurses code, for example, and ... well, let's just say you *don't* want to try this at home, you may be scarred for life. :-P T -- Let X be the set not defined by this sentence...
Aug 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Aug 16, 2013 at 10:24:55PM +0200, Andre Artus wrote:
 On Friday, 16 August 2013 at 17:45:35 UTC, Suliman wrote:
On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
I would like to contribute to the D ecosystem, but as I'm still
in the learning process I do not want to get my sticky fingers
all over someones nice clean code.

I have poured over the documentation and see that there are a
few low-hanging fruit that I would like to pluck. So I have
decided to do so.

I would like for there to be a section were people interested in
working on the docs can collaborate.

It would be perfect to get D version of http://www.dotnetperls.com/

That's pretty cool. It would be good to have something like that for D, or a "Ninety-Nine D Problems", or a Try-D, or an update to http://en.wikibooks.org/wiki/D. I'm wiling to work towards those goals. There are a number of good articles and other D materials strewn around the web, perhaps we can find place to include or link to them from dlang.org.

I think wiki.dlang.org is a good place to put little gems like this. It allows easy community effort to edit, and serves as a central place for people to go when they want to find example D code for a particular task. Vladimir has been very kind to offer hosting for wiki.dlang.org, so let's make use of it. T -- Век живи - век учись. А дураком помрёшь.
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 20:12:20 UTC, Jonathan M Davis wrote:
 On Friday, August 16, 2013 21:57:01 Andre Artus wrote:
 It is disheartening to think that the people with potential for
 the most valuable contributions or insight will be avoiding
 discussions regarding the documentation. But I fear you are
 correct.

There's a difference between avoiding discussions and searching after them. If a discussion occurs in a list that they're already subscribed to, they're a lot more likely to read it and contribute to it than they are to go and subscribe to yet another list. - Jonathan M Davis

I just noticed when posting my previous reply to you that it connected to an NNTP server (I normally context switch on anything that takes more than a fraction of a second, so I have not seen it before). So I guess that many forum users interface via a newsreader. That's seriously old-school.
Aug 16 2013
prev sibling next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Fri, Aug 16, 2013 at 10:52:11PM +0200, Andre Artus wrote:
[...]
 I just noticed when posting my previous reply to you that it
 connected to an NNTP server (I normally context switch on anything
 that takes more than a fraction of a second, so I have not seen it
 before). So I guess that many forum users interface via a
 newsreader. That's seriously old-school.

Actually, there are several things going on here: the forums themselves are hosted on NNTP servers, but IIRC very few members actually use NNTP directly. Instead, some proportion use the SMTP mailing list gateway (which runs mailman, which has a long-unfixed issue which sometimes rewrites the wrong message IDs, causing threads to break), and others use the web interface on dlang.org. But you know what's *really* old-school? IPv4, which was drafted in 1981. And a large segment of the internet still uses it. :) (And that's in spite of doomsday predictions about IPv4 address space exhaustion -- IPv6 adoption is still slow in many parts of the world in spite of the address exhaustion having already taken place.) T -- Frank disagreement binds closer than feigned agreement.
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 20:42:28 UTC, H. S. Teoh wrote:
 On Fri, Aug 16, 2013 at 10:24:55PM +0200, Andre Artus wrote:
 On Friday, 16 August 2013 at 17:45:35 UTC, Suliman wrote:
On Friday, 16 August 2013 at 16:07:59 UTC, Andre Artus wrote:
I would like to contribute to the D ecosystem, but as I'm 
still
in the learning process I do not want to get my sticky 
fingers
all over someones nice clean code.

I have poured over the documentation and see that there are a
few low-hanging fruit that I would like to pluck. So I have
decided to do so.

I would like for there to be a section were people 
interested in
working on the docs can collaborate.

It would be perfect to get D version of http://www.dotnetperls.com/

That's pretty cool. It would be good to have something like that for D, or a "Ninety-Nine D Problems", or a Try-D, or an update to http://en.wikibooks.org/wiki/D. I'm wiling to work towards those goals. There are a number of good articles and other D materials strewn around the web, perhaps we can find place to include or link to them from dlang.org.

I think wiki.dlang.org is a good place to put little gems like this. It allows easy community effort to edit, and serves as a central place for people to go when they want to find example D code for a particular task. Vladimir has been very kind to offer hosting for wiki.dlang.org, so let's make use of it. T

You have a good point, maybe we should consolidate the How-to's and the Articles on one or the other site and provide links to it from the other site. For the time being I think getting the Library and Language references cleaned up could probably be of greatest value.
Aug 16 2013
prev sibling next sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 20:03:10 UTC, H. S. Teoh wrote:
 On Fri, Aug 16, 2013 at 08:25:00PM +0200, Andre Artus wrote:
 On Friday, 16 August 2013 at 18:09:04 UTC, Andrei Alexandrescu
 wrote:

Things should happen organically, i.e. creating a specialized
group should follow a need substantiated by increased volume 
of
specialized discussion in the general group. At this point 
there
is nothing in that vein.


 I understand were you are coming from. And, while I currently 
 feel
 that it's a bit of a catch-22 situation, I think it is worth at
 least trying out your suggestion of marking document related 
 threads
 with "[dox]".

Alright, I'll start. Here's a list of Phobos modules that need some documentation facelist. For fairness' sake, I gleaned these from: http://dlang.org/phobos-prerelease/index.html as opposed to the docs for the official release, so that they closer reflect what things will look like at the next D release. 1) The above page itself needs work. Right now it's just a very spotty incomplete list of seemingly-random pieces of Phobos. It looks like the relic from a bygone era before Phobos docs had a navbar on the left; so my first thought would be to kill off that incomplete module list (leave that to the navbar). My second thought would be to group the modules under more logical categories so that newbies would know which modules tend to be used together (e.g., std.algorithm and std.range tend to be used together a lot IME). 2) std.algorithm: the state of the current docs is not bad, but could use some improvement. The first paragraph could be expanded to explain what this module is all about. The part about string lambdas (2nd paragraph) may need to be tagged with a note about possible deprecation, judging from discussions in the other thread. If not, at the very least the code example should show how to use the new lambda syntax: sort!((a,b) => a < b)(...); I'm not sure what to make of the cheat sheet, as it seems to repeat most of the table of links at the top of the page. But maybe it's good for short code snippets to remind you how to use each function, so maybe it can be left alone for now. 3) std.array: desperately needs a more detailed explanation at the top to explain why this module is even needed (newbies would wonder: doesn't D have built-in arrays? Why do we need this module then?). Not enough code examples. 4) std.ascii: unhelpful description. Why do we even need this module when D uses UTF-8 by default? When should we use this module and when should we use std.uni? Also, needs an overview of what this module provides (string constants, character categorization, case conversions). 5) std.base64: unhelpful description. Doesn't explain what is base-64 and why we should care. What are the applications of base-64 anyway? Who would want to use this stuff? Without more details, a newcomer wouldn't know. 6) std.bigint: badly needs more code examples, with explanations. 7) std.bitmanip: needs more explanation about what this module is, why we need it, etc.. Needs categorization of what is provided (bitfields, endianness-related functions, anything else). 8) std.compiler: need code examples of how to use the stuff here. Maybe using version blocks. Maybe sample music composed in D_major... oh wait. Wrong forum. :-P 9) std.complex: needs more code examples. Maybe a little more explanation about what's going on with "built-in types" and why those will be replaced. 10) std.concurrency: needs higher-level module description, like what's the use of low-level messaging systems. Need to provide adequate context for where/when this module should be used. Needs to link to other doc pages that discuss threads, processes, etc.. 11) std.container: badly needs a better description. The table of operations with complexity guarantees needs a bit more explanation about what this all means. Maybe a link to somewhere (wikipedia perhaps) that explains the concept of complexity and why it matters. Also, need an overview of what containers are provided and example code on how to use them. 12) std.conv: the one-line description is cute, but inadequate. Need code examples on common usage. Need to explain in more detail how to make user-defined types usable with to!() (e.g., need to define opCast, ctor requirements, etc.). Need module overview about what's provided (to, octal, parse, emplace). Need code examples. 13) std.csv: Not bad, but could use an overview of module contents with links to each main function/struct (ala std.algorithm / std.range). 14) std.datetime: Not bad. It would be nice to add links to actual functions/types in the module overview. 15) std.encoding: needs more code examples. Overview of module contents. 16) std.exception: needs higher-level overview of what's in this module, with categorized functions/types. Code examples for assertThrown & co., as well as explanations of why we need them. 17) std.file: needs more code examples. Module contents overview. 18) std.format: there are a lot of good docs here, but buried in hard-to-find places. Needs module overview, with code examples. There also appear to be some DDOC typos here. Especially needed is: how to make your own user-defined types usable with std.format. What are the possible hooks, example code of how they are used, etc.. 19) std.functional: need more explanation of what this module is all about. Motivation: why do we care about functions manipulating other functions? There are some code examples here but could use better motivated examples, like when/where such features would be useful. How this relates to functional programming, etc.. 20) std.getopt: not bad. Maybe add some examples of an actual shell session and how getopt parses things. Explain what args[0] means (this is very non-obvious to people unfamiliar with command-line UIs!). 21) std.json: needs proper description and code examples. 22) std.math: needs categorized summary of module contents. 23) std.mathspecial: needs code examples. Explanation of why this isn't part of std.math. 24) std.mmfile: needs a LOT of explanation of what this is, and why it might be useful. Code examples. 25) std.numeric: needs adequate explanation of what this module does and why it's needed. Why isn't it part of std.math, what's the difference, etc.. Categorized summary of module contents. 26) std.outbuffer: needs explanation of what this module is. Code examples. 27) std.parallelism: not bad. A linked overview of module contents would be nice. 28) std.path: needs linked overview of module contents. Why this isn't part of std.file. In fact, the Phobos index page should group std.file, std.stdio, and std.path together, and explain what's the difference between them, and what each module covers in terms of file-related operations. 29) std.process: pretty good! Maybe explain how this relates to std.parallelism, std.concurrency, etc.. The difference may not be obvious to newcomers. Possibly put this explanation in the Phobos index page. 30) std.random: linked overview of module contents would be nice. More code examples. Maybe a brief discussion on various RNG issues, like measure of randomness, reproducible/non-reproducible sequences, cryptographic strength, etc.. 31) std.range: not bad (if I say so myself ;-P). More code examples would be nice. As well as motivating examples of when you might want to use each range type. 32) std.regex: pretty good! 33) std.signals: ugly. The links to various forum discussion threads is a poor substitute for a well-written summary of the contents of said discussions. Needs more code examples and applications. 34) std.socket: needs a module description!! And many more code examples. And module contents overview. 35) std.socketstream: not sure if we want to spend more effort documenting this, since it's slated for replacement, but might not hurt in the short term to do so. 36) std.stdio: very unhelpful description. Should explain exactly what this module does for people who *don't* know C, what types / functions it exports, code examples of how to use them. E.g., how to open / close a file, how to read/write text data, how to read/write binary data. Explain range interface for files. Caveats on the transience of byLine. 37) std.cstream, std.stream: not sure how much to do for these, since they're slated for replacement. 38) std.string: need better description. Why this module exists (aren't strings built-in in D?), what it provides (linked overview of contents), more code examples. 39) std.system: explain what this module is, why we need it, when it should be used. Code examples (*motivating* code examples, not just random code snippets that happens to use the symbols exported here!). This should be grouped with std.compiler in the Phobos index page. 40) std.traits: need to elaborate on description. Brief discussion of metaprogramming maybe? With motivating code examples. Need linked overview of contents. There's a lot of stuff in here; grouping into logical categories should be more helpful. 41) std.typecons: need better description. Explain basic usage, what it means, etc.. The current code example is rather abstruse to a newcomer; needs more down-to-earth explanations of what exactly is going on in the code. Needs overview of contents. More code examples. Things like Flag should be highlighted so that newbies pick up on the concept and use Flag instead of bools everywhere. 42) std.typetuple: need proper explanation of the difference between TypeTuple, std.range.Tuple, and compile-time "tuples" (SymbolTuples, as Ali calls them). This is very confusing for newbies (and even for experienced D coders!). Overview of module contents. 43) std.uni: I think Dmitry's new std.uni hasn't been updated on dlang.org yet, so I'll refrain from commenting for now. From what I remember, the new docs (and code, of course!) are far better than the one you see on dlang.org, so probably we don't have to worry about it. 44) std.uri: the description could use some elaboration. And code examples. 45) std.utf: need to elaborate description. How this relates to std.uni. Example code. Issues to deal with when interfacing with C code (toUTF*z). 46) std.uuid: not bad! 47) std.variant: not bad. Could use more code examples in a few places. Maybe higher-level discussion of usage, motivation, potential issues, etc.. Overview of module contents. 48) std.xml: slated for replacement; so just let be for now? 49) std.zip: Need better module description, overview of contents. How this relates to std.zlib. 50) std.zlib: why this isn't part of std.zip. Code examples!! 51) std.net.curl: not bad. 52) std.net.isemail: need code examples! 53) std.digest.*: not bad! Phobos index page needs to group these together and explain how each piece relates to the others. 54) std.windows.charset: explain why this isn't part of std.encoding. Code examples. (Also, why is the CSS broken for this page on dlang.org?) Phew, I never realized Phobos was *this* big! This covers only std.*, but there's still etc.* and core.*. Lots of work ahead of us! T

This is great, I'm busy working on some parts of the Language docs so I have not read through your entire list, but I have a short example to core.time. There is a script running on the page you linked to that is making my browser misbehave. It's probably not helped by the fact that I have a browser tab open for every page on the interwebs.
Aug 16 2013
prev sibling next sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Friday, August 16, 2013 14:04:48 H. S. Teoh wrote:
 Actually, there are several things going on here: the forums themselves
 are hosted on NNTP servers, but IIRC very few members actually use NNTP
 directly. Instead, some proportion use the SMTP mailing list gateway
 (which runs mailman, which has a long-unfixed issue which sometimes
 rewrites the wrong message IDs, causing threads to break), and others
 use the web interface on dlang.org.

I'm pretty sure that there are quite a few folks using NNTP still (e.g. IIRC, Walter uses Thunderbird as an NNTP client), but we'd have to do a poll to be sure. Certainly, a large portion of the posters who have been here for a while use either the mailing list or NNTP, since the current web interface is fairly new. - Jonathan M Davis
Aug 16 2013
prev sibling parent "Andre Artus" <andre.artus gmail.com> writes:
On Friday, 16 August 2013 at 19:32:41 UTC, Mr. Anonymous wrote:
 On Friday, 16 August 2013 at 19:27:58 UTC, Andre Artus wrote:
 On Friday, 16 August 2013 at 19:12:46 UTC, Mr. Anonymous wrote:
 On Friday, 16 August 2013 at 18:12:57 UTC, Andre Artus wrote:
 Is there a way to break the pages into a more of a 
 hierarchy, so that documentation for each module doesn't 
 have to be on one page? Perhaps a DDOC Section could 
 indicate the category?

Are you familiar with DDOX? http://vibed.org/temp/d-programming-language.org/phobos/index.html

I have not yet had the time to look into it, but I fear that it would be of little use if it's not the official way of doing docs. Although it may be the preferred option for private projects or projects not directly connected to the main D ecosystem. There is already quite a lot of fragmentation making it quite an effort to find out what the "one true path"[1] is. 1. I realize that there isn't truly such a thing, but an opinionated starting point is of great help to noobs. The major feature to popularize Ruby on Rails when it first kicked off was, in my opinion, the "on rails" part. You had a very clear indication of where to start, and what the best/accepted/expected practices are. Once you have accustomed yourself to the language and framework you can find ways to go crashing through the bushes if you feel the need to do so.

It's planned as the official way of doing docs. There are pull request for it, but it's going nowhere for the past several months. A related thread: http://forum.dlang.org/thread/dsnpggjmndaxiusfqhjk forum.dlang.org

I have looked at it now, and it seems to me to be a great improvement but the content needs to be updated. If this is going to be the new official way, and all that is needed is someone to start porting/updating the content then I'll sign up for that. I think it wise to first get it up to date before doing major new additions. Who is working on this at the moment?
Aug 17 2013