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.
