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

[aldanor via Digitalmars-d]

On Friday, 23 January 2015 at 18:17:30 UTC, H. S. Teoh wrote:
> Well, to be fair, the reason Ali's book is so detailed is 
> because it's
> geared towards the newbie programmer who is learning how to 
> program,
> possibly for the first time. So the pacing isn't really suited 
> for an
> experienced programmer who just wants to learn D as an 
> additional
> language. The material is excellent, no doubt, but probably 
> needs
> repackaging to target the seasoned programmer.
Agreed. I think that's exactly the target audience (and exactly 
the one that we are missing the proper docs/guide for). After 
all, D is not a "learn me a ruby in 15 minutes" kind of language, 
so the chances are whoever's coming here has a vague idea of what 
they expect or what they want to learn about D. Just as an 
example, I've heard a lot of D talk on #rust-offtopic irc -- 
those folks would barely qualify as beginner programmers.

> I vote for ddoc / static generation. The site itself is static 
> anyway,
> using client-side JS to do this seems to be overkill.
You need both. What I meant was that DDOC has to be able to 
generate an index (one huge dict) and store that in a text 
file/json. The client-side would just use that "database" to 
provide on-site incremental search. Quite easy.

> If we don't have one, then the obvious first step is to begin 
> writing
> one. :-)
>
> And when I said you should spearhead this effort, I don't mean 
> you
> should do everything yourself. That's not feasible for obvious 
> reasons.
> Rather, the community can and should help -- but you do need to 
> take the
> lead in the effort, otherwise there will be no focused 
> direction and
> things will go nowhere after 2 months.
>
> For example, you could come up with an initial draft or 
> proof-of-concept
> and put it in a github fork where people can submit PRs to 
> flesh out the
> skeletal ideas / outline you lay down as a first stab. Then you 
> can
> solicit for feedback -- that's part of the role of spearheading 
> the
> effort -- and oversee the overall direction. That way it's not 
> just you
> who's put on the spot to do everything, but everyone can 
> contribute and
> make it better than any single one of us can by ourselves.
>
> Or, for an even less daunting start: start submitting PRs for 
> draft
> tutorial pages and code examples, and encourage others to do 
> the same.
> Nothing gets things moving more effectively than having actual 
> code /
> docs sitting in the PR queue ready to be merged. OTOH, too many 
> forum
> threads (well-intentioned, mind you) tend to just fizzle out 
> after a
> while and nothing gets accomplished.
Thanks for clarifying. I too hope this thread doesn't just become 
another bikeshedding timesink :) I'll get some style-related 
drafts published on the weekend and then we'll see how it goes 
from there. Indeed, I won't mind to "spearhead" this (if I knew 
how!) since the whole documentation story is very sad, provides D 
with negative publicity and provides users like us with constant 
annoyance (but... it can be fixed -- we all know it).