Some feedback on the website.

[John Colvin via Digitalmars-d]

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.