dlang.org redesign -- the state of documentation and learning resources [part 2]

[aldanor via Digitalmars-d]

On Friday, 23 January 2015 at 17:19:44 UTC, H. S. Teoh wrote:
> OTOH, do I hear the cry of a volunteer? ;-)  (I'm only 
> half-joking...
> the thing is, if nobody steps up to write said tutorial, it 
> isn't gonna
> materialize. The rest of us are already busy enough with 
> whatever it is
> we're contributing to D.
I could try in my spare time but I don't think I qualify as a D 
guru since there are some shady D areas I have yet to learn 
properly myself. It has to be a collaborative effort.

On Friday, 23 January 2015 at 17:19:44 UTC, H. S. Teoh wrote:
> Having said that, though, I thought Ali's D
> book is pretty good in terms of serving as a beginner's 
> tutorial to D?
> Or do we need a different one more geared towards seasoned 
> programmers?
> (Ali's book is primarily targeted towards newbie programmers).)
Ali's book is VERY good. The best part is that you can load it on 
Kindle / tablet / whatever (I did!) and take it with you. 
However, it's _not_ an official "30 minutes to D" guide. It's 
more like "1 month to D if you survive it" because it's very 
thorough and detailed. Come on, it's a bit too boring to only get 
to a for loop in chapter 10 if I'm just excited to see what the 
language is all about. For instance, I'm fairly certain that 
metaprogramming (at its simplest) should appear early in the 
guide.

> Yeah I've run into the same problem. Google search does not 
> eliminate
> the need for a proper, well-thought-out, navigable index.

> I'm thinking perhaps an autogenerated alphabetical index of all 
> symbols
> might be in order here?
Yep, see my post above re: the incremental index. It's absolutely 
doable with DDOC / client-side JS.

> Easy. We pick a suitable beginner's tutorial -- either Ali's 
> excellent
> book or something you or some other volunteer writes up, and 
> put a big
> fat link to it in a prominent place on the front page. Problem 
> solved.
The problem is - I don't think we actually have one. And it 
really has to live on dlang.org to feel official and up to date. 
It has to be reasonably succinct but exciting, not too formal, 
well-styled, with links to official docs and "read more there and 
there" anchors.

> If you're not happy with Ali's book, please contribute your 
> own. I'm
> pretty sure the dlang.org maintainers will be more than glad to 
> include
> it.
I (personally) am happy with Ali's book of course! But as I've 
already said a link to the book != a proper _official_ 
introduction. It could largely overlap though, that's true.

> Would you like to step up and spearhead this effort?
Not alone by myself, that's for sure :) Ideally, someone who's 
already done a considerable amount of work on a book / docs, of 
course...

> Good! So let's see the PR's. :-)
This needs to be well thought through :) But if noone objects to 
the style of "Rust by Example" which I tend to like -- perhaps we 
could come up with something similar (and perhaps more 
interesting, especially when it gets to all the metaprogramming 
jazz).