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).
