Some feedback on the website.

[H. S. Teoh via Digitalmars-d]

On Wed, Dec 16, 2015 at 08:05:03PM +0000, Vladimir Panteleev via Digitalmars-d 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.

Yeah, this is like spaghetti code written with C macros, where all macro
names are in the same namespace, there is no scoping (everything is
global), and undocumented so nobody knows what's already there or when
to use what, and reinvents their own unhelpfully-named macros. Worse
yet, sometimes people write their own implementations of existing macros
with the same name so it's far from obvious which macro is actually in
force when a particular part of the website is being processed -- this
actually happens in the dlang.org repo: try grepping for XREF or LREF
sometime, and see how many different definitions there are, for example.
Or how many different macros there are for generating hyperlinks -- when
should each one be used? Who knows. Read the code^Wmacro definitions to
find out.

Also, the lack of flexibility in number of macro arguments means you end
up with LINK, LINK2, LINK3, etc., with no obvious indication what the
difference is and where you should use which macro. It's like a
worst-case scenario C library that has printf1, printf2, printf3, ...,
instead of printf, fprintf, snprintf, etc., and people are expected to
remember which numerical suffix does what.

It's relatively easy to keep track of this in single-person projects --
Walter's using ddoc for creating ebooks, for example -- but in large
collaborative projects these seemingly-minor issues lead to spaghetti
macro-ni soup. The messy, inconsistent tangle that is the dlang.org
macros constitute a high barrier-to-entry for would-be contributors.
Mostly people just end up copy-n-pasting stuff without understanding
what's really going on.  We're at the ironical situation where ddoc
macros need their usage documented -- by another ddoc page? :-P


T

-- 
There is no gravity. The earth sucks.