Website message overhaul

[Bane]

Andrei Alexandrescu Wrote:

> On 11/18/11 1:15 PM, Bane wrote:
> > <rant> As a language claiming for itself it was created out of
> > practical needs of programmers I must say D fails on that test (both
> > compilers and D website). It is not user friendly. It is user
> > hostile, for simplest and most common tasks. Especially for newbie
> > programmers.
> >
> > It was like that 4 years ago when I first saw it, and it is much
> > like that now.
> 
> Is that the language, compiler, environment, or website? I got a bit 
> confused.

Website problems I think should be sorted out:
 - D1 vs D2, which to choose, what are differences between them etc. Too unclear and discouraging for a newcomer.
 - Too much old and unnecessary info. Too much redundant text. I suggest going again from scratch or just start using delete key without restrictions. Just one example: a lot is written about benefits of exception handling vs. C like return values etc. It is practically proven that approach is useful, nobody questions that. There is no need to clutter documentation with articles like that. Things like that should be shelved on some "old docs" place, not on prime pages.
 - Generally feeling "lets stuff as much info as possible here, and don't delete anything - it may be useful for somebody" that just overwhelms first time reader and distracts him. 

> 
> > You people should really hire some non-programmers with documenting
> > skill and knack for KISS principle to make D website and
> > documentation. It is obvious that Walter, Andrei and the rest of
> > core people are highly skilled in their field of work, but not
> > interested, available or competent to present D complexity in
> > simple, right-to-the point way.
> 
> Right now D is pushed forward by volunteer work. Indeed it would be 
> great if more articles and tutorials were available.

I paused with D last year after (yet another) unsuccessful attempt to port my code from D1 to D2. reason: shared stuff. More specific reason - is it a bug with my code or docs ain't exact or that feature isn't working yet (even docs claim it works?)?

So, I guess problem is correctness of manual for D2.  Digging trough this newsletter to find is some feature working and how is terrible way for learning.

> 
> > I guess it is so much more fun to add new features and optimize code
> > than to organize and present all the documentation the way it can be
> > useful.
> 
> Fun doesn't have a lot to do with it.

Well... we wouldn't be here if we don't find programming fun (too).

> 
> > And come on, BUD like feature is first useful thing compilers are
> > lacking. Talking about practical need. </rant>
> 
> Agreed. To add to that, I am a bit worried that the most worked-on build 
> management tool uses D1 and Ruby.
> 

It strikes me very bad seeing there are/were more than one project published (bud, dss etc. i might be mistaking) and god knows how many people made their solutions for internal work just to simplify task of compiling multiple files and yet - compilers still lack that feature. 

A lot of work invested in D tools just rot away because it is not incorporated into core, or ad least mentioned in proper docs "Hey guys, compiler don;t has feature Y yet, but here is official tool for that here, use it - just don't reinvent the wheel again".

And there goes same with lot of small things.

People who want D to succeed should start collecting those fruits and putting them where they can be seen.

> 
> Thanks,
> 
> Andrei