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.

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

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

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

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.

>> 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.
>>>
Archive, don't delete.

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

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

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.

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.
>>>>
> Archive, don't delete.
>
> 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)

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