On 12/15/2015 05:45 PM, Jack Stouffer wrote:
> Also, you saying "even if it's not an actual improvement"  is a real
> head scratcher for me. We need a change even if it makes things worse?

It's visuals, not engineering. Put your artist hat on. "Not better" does not mean "worse". -- Andrei

On Wednesday, 16 December 2015 at 01:18:03 UTC, Andrei Alexandrescu wrote:
> This is easy to refute because only one counter-example is needed. I made a bunch of non-improvement changes in early 2014. The success was tremendous. -- Andrei

Was it? How did you measure the success?

On Wednesday, 16 December 2015 at 01:18:03 UTC, Andrei Alexandrescu wrote:
> On 12/15/2015 05:45 PM, Jack Stouffer wrote:
>> On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu wrote:
>>> Yes, the css has grown long in the teeth. Just replacing it with
>>> something else is needed, even if it's not an actual improvement.
>>
>> I have to disagree with you heavily on this point. Changing the look and
>> feel of a site just for the sake of change is a lot of work for little
>> gain.
>
> This is easy to refute because only one counter-example is needed. I made a bunch of non-improvement changes in early 2014. The success was tremendous. -- Andrei

Yeah that is important. That's the difference between and iPhone and other phones. It does the exact same thing, yet people are willing to pay $200 more.

On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei Alexandrescu wrote:
> It seems knowing ddoc is part of knowing D. -- Andrei

I just cargo cult something when I contribute to phobos/druntime. One cannot know everything.

Also, ddoc always appeared to me like a big NIH syndrome.

On 2015-12-15 14:15, Andrei Alexandrescu wrote:

> I'm not sure about this. There are very very many potential improvements
> that are important, easy to do, not related to the use of ddoc, and
> don't get done.

One still most likely need to build the site, which is kind of a pain to do.

-- 
/Jacob Carlborg

On 2015-12-16 02:15, Andrei Alexandrescu wrote:

> It seems knowing ddoc is part of knowing D. -- Andrei

I'm wondering how you can think it's perfectly acceptable to invent our own (crappy) language for documentation and at the same time loudly complain that SDLang is use for Dub config files and not a (more widely) standardized format.

-- 
/Jacob Carlborg

On Wednesday, 16 December 2015 at 02:01:02 UTC, deadalnix wrote:
> On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei Alexandrescu wrote:
>> It seems knowing ddoc is part of knowing D. -- Andrei
>
> I just cargo cult something when I contribute to phobos/druntime. One cannot know everything.
>
> Also, ddoc always appeared to me like a big NIH syndrome.

Well DDoc may have it's disadvantages, but I'm certain that the documentation would have been far worse if it wasn't for it.

What I like about it:
+ Good defaults for sections
+ Params section is checked at compile-time and has nice syntax
+ Everything that is not builtin can be implemented as a macro.
+ Recently added feature that allows you to wrap code with ` ` like in markdown

What I don't like about it:
+ It relies too much on macros for some of the stuff that could have been builtin
+ This makes reading the docs in the source code of some phobos function harder, because you need to mentally expand the macros
+ The macro syntax probably should have been something like ${MACRO ...} because ( and ) are more often used symbols and syntax should be optimized for them (so you don't have to escape them).

In general I prefer markdown's syntax for things like lists, links, tables, bold and italic text, because it is more easily readable and writable by humans.

On 12/16/15 2:56 AM, Jacob Carlborg wrote:
> On 2015-12-15 14:15, Andrei Alexandrescu wrote:
>
>> I'm not sure about this. There are very very many potential improvements
>> that are important, easy to do, not related to the use of ddoc, and
>> don't get done.
>
> One still most likely need to build the site, which is kind of a pain to
> do.

Building the site mimicks building dmd, druntime, and phobos. It's an invocation of make. What are the difficulties? -- Andrei

On 12/16/15 3:00 AM, Jacob Carlborg wrote:
> On 2015-12-16 02:15, Andrei Alexandrescu wrote:
>
>> It seems knowing ddoc is part of knowing D. -- Andrei
>
> I'm wondering how you can think it's perfectly acceptable to invent our
> own (crappy) language for documentation and at the same time loudly
> complain that SDLang is use for Dub config files and not a (more widely)
> standardized format.

What standardized format was dominant in 2001? Thanks! -- Andrei

On 12/15/15 9:01 PM, deadalnix wrote:
> On Wednesday, 16 December 2015 at 01:15:45 UTC, Andrei Alexandrescu wrote:
>> It seems knowing ddoc is part of knowing D. -- Andrei
>
> I just cargo cult something when I contribute to phobos/druntime. One
> cannot know everything.

Very reasonable, thanks. But that comes with an implied non-nagging agreement :o).

> Also, ddoc always appeared to me like a big NIH syndrome.

What would you have done instead?


Andrei