Recently I've seen documentation work, but am confused about some specifics.

I've seen work and/or talk being done towards...

1. Improving the text of the documentation itself
2. Improving ddoc with some Markdown capabilities
3. Moving Phobos docs to page-per-symbol
4. Adding adding discussion to documentation pages
5. Moving Phobos docs from ddoc to ddox

While I appreciate (1) and (2), I don't see the appeal of (3), and am strongly opposed to (4) and (5).

As I see it (3) only serves to make it harder to browse the documentation and increases server load, but I can probably live with it if other people think it is a good idea. I should point out that I'm not aware of any other quality web-based docs for *anything* that put each symbol on its own page.

I also don't like the idea of (4), because it is a huge extra moderation requirement which I don't think this community can actually handle, and it will only age, causing it to be yet another source of wrong information about Phobos/D.

However, my main concern is with (5), which leads me to some questions:

 * If ddoc is good enough for Phobos, why use another semi-compatible tool?
 * If ddoc isn't good enough for Phobos, why is it in the compiler?
 * If we want ddoc in the compiler, then why not dogfood that for Phobos?
 * If we don't want ddoc in the compiler, why is spend time improving it?

Thanks.

On 1/11/15 1:41 PM, Confused wrote:
> Recently I've seen documentation work, but am confused about some
> specifics.
>
> I've seen work and/or talk being done towards...
>
> 1. Improving the text of the documentation itself

Yes please.

> 2. Improving ddoc with some Markdown capabilities

We have https://github.com/D-Programming-Language/dmd/pull/4228 about to make it - for now I think that's going to improve things significantly.

> 3. Moving Phobos docs to page-per-symbol

Yah, though quality is not there yet.

> 4. Adding adding discussion to documentation pages

Yah.

> 5. Moving Phobos docs from ddoc to ddox

Yah, though again we need serious work on quality.

> While I appreciate (1) and (2), I don't see the appeal of (3), and am
> strongly opposed to (4) and (5).
>
> As I see it (3) only serves to make it harder to browse the
> documentation and increases server load, but I can probably live with it
> if other people think it is a good idea. I should point out that I'm not
> aware of any other quality web-based docs for *anything* that put each
> symbol on its own page.

No worries, the extant docs are here to stay. I plan to put at the beginning of each module a link with text like "See single-page documentation".

> I also don't like the idea of (4), because it is a huge extra moderation
> requirement which I don't think this community can actually handle, and
> it will only age, causing it to be yet another source of wrong
> information about Phobos/D.

The way I see it is: to swim, we gotta get out feet wet.

> However, my main concern is with (5), which leads me to some questions:
>
>   * If ddoc is good enough for Phobos, why use another semi-compatible
> tool?

Mostly because it's there. It's possible to make ddoc generate file-per-entity or automatic cross-indexing. It's been on my list for years, but still haven't gotten to it. So why not just ddox? (It does build now.)

>   * If ddoc isn't good enough for Phobos, why is it in the compiler?

ddoc is a terrific and incredibly underrated tool, which can (and should and probably will) be taken further with simple improvements. Note that ddox also works on top of ddoc. Also, again, the ddoc-generated documentation is plenty good and will continue to be available.

>   * If we want ddoc in the compiler, then why not dogfood that for Phobos?

It is and it will continue to be there. Oh, one more thing - the website pages proper (language reference) use ddoc.

>   * If we don't want ddoc in the compiler, why is spend time improving it?

We do want and we should spend.


Andrei