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