Better docs for D (WIP)

[Adam D. Ruppe via Digitalmars-d-announce]

On Friday, 1 January 2016 at 16:30:44 UTC, Bastiaan Veelo wrote:
> In my eyes there are three important aspects to quality 
> documentation:

Let me summarize the benefits I see in my way for each of these 
three items:

>  1. Content

For content, I'm making edits based on common questions I see. 
I've answered like 1/4 of all the D support requests in 2015 
myself and there's a lot of patterns there. I'm also talking to 
new users and watching them code to see what problems they have 
myself.

Doing these edits on the status quo keeps getting blocked by the 
overhead... we have a content problem in part because of the 
process/infrastructure problem.

>  2. Usability (legibility, X-ref, list of contents, indices, 
> searching)

This is what the new generator does by rearranging and formatting 
the content. There's a new feature: $(REF ), which is a smarter 
reference than plain text macros allow, and header macros are 
built-in so the processor understands how to build a table of 
contents out of them too.

>  3. Maintainability (ease to contribute, legibility in code, 
> intuitive procedures)

Ease and intuition: I'm creating a web interface to drop 
suggestions and to preview your new articles. You don't have to 
build the whole site (which also requires git phobos and git 
dmd...), just upload your new file.

The final thing will still be a github pull request, but for many 
cases I can help myself by doing it.

Legibility: I'm limiting ddoc macros to keep them simpler to 
understand. A comprehensive, but limited set of syntax allows you 
to actually learn it all and use them as you write without 
worrying about what weird user-defined macros are there or what 
the difference between XREF and XREF2 is.

Most documentation should use this fancy syntax sparingly.

> there is too much friction that this be done in the official 
> documentation. But if it is too much for Adam, I am not 
> encouraged to even try...

Well, remember that I'm extremely lazy. You should still try it 
yourself to understand what I mean and see if you agree.