On Wednesday, 16 December 2015 at 20:05:03 UTC, Vladimir
Panteleev wrote:
On Tuesday, 15 December 2015 at 21:45:02 UTC, deadalnix wrote:
On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei
Alexandrescu wrote:
On 12/15/15 5:54 AM, tcak wrote:
The harder it is made for people to contribute the system
for fixations,
the lesser changes are seen.
I don't think we've had many contributions via the "Improve
this page" button.
I don't know how representative it is, but once in a while, i
forgot all of this is in DDoc, I notice something, what to do
a quick patch, and end up being reminded this is in DDoc and I
have no idea how to fix the thing, because suddenly, what
looked like a quick fix end up being learning a new macro
language.
DDoc itself is very simple. The problem is the endless number
of macros we use on dlang.org. E.g. all the different ways to
link to something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB,
LREF, XREF, XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF,
COREMODREF, OBJREF... There is also no strong reason to use
e.g. DIVCID instead of plain HTML.
The number of macros bothers me, but mostly it's the complete
lack of documentation and guidelines on where/how to use them*.
It's pretty unreasonable to expect someone submitting a passing
doc fix to
1) find where the macros are defined
2) decipher them
3) use the "right" one**
It's just too much unpleasant work for people to bother with.
*If there is documentation and guidelines on this and I don't
know about it, consider what it would be like for someone who
doesn't spend many hours a week on the various subdomains of
dlang.org: it might as well not exist!
**there must be some reasons for the existence of all of those
macros, so presumably there are good and bad choices for certain
situations, even if nothing is obviously broken using the bad
choice. Sure, we might say "submit something naïve and then
people will help you fix it", but that's still a barrier to
entry; 1) how were they supposed to know we felt that way about
submissions? 2) people don't like looking stupid.
