FYI, even now, I hesitate to change links in my Phobos fork because I kinda want to remain ddoc compatible... and I can never remember what macro it is. And I've been kinda deep in this the whole last week.


Anyway, let's get into this:


On Sunday, 3 January 2016 at 23:16:30 UTC, Andrei Alexandrescu wrote:
Do the projected advantages of Adam's project do not include ease of contribution? If so, how?

1) a massively simplified build. Indeed, I'll make a web form so you don't even have to have dmd installed to make some docs.

This got posted today:
https://issues.dlang.org/show_bug.cgi?id=15516#c2

Two people whose names I recognize who have been with D for a long time didn't know how to add a page to the website. And what they did figure out was a multi step process.

My system already runs a single file or an entire directory and just works. It will never forget a file because you didn't add it to mak/DOCS of win32.mak or anything else.

I'll also make a web form to upload new pages and probably entire projects for automatic processing too.


2) My linking system already works better than ddoc allows. You can reference with a single macro: $(REF some.name). I also keep MREF, XREF, and a few others for legacy phobos+ddoc compatibility, but the user doesn't have to know a hundred obscure macros. (There's about a half-dozen simple ones instead, plus a few thin wrappers over HTML which I might kill but might not since they don't really bother me.)

Combined with the ease of adding all new files, contributors can just link new articles they write to go in depth without worrying about process.



3) I'm also going to make a dynamic webpage once I declare this beta where viewers will be given random pages and asked to eyeball it for me. If they flag it as buggy - with a single click on the page, no bugzilla signups - it'll contact me and I'll work on the bug.

If they want to contribute to content, I can pull up the existing comment source code and present it right there, again likely emailed to me for integration, or the source location can be opened in Phobos for a traditional pull request.

This will encourage crowd sourcing doc bug fixes.


4) I'll never complain about spaces vs tabs, line length, or any other trivial nonsense. If I don't like that stuff, I'll just fix it myself instead of letting the PR wither and die while letting the contributor feel undervalued.


Reply via email to