Can we get a forum section devoted to documentation? [dox]

[Andre Artus]

> 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.