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

[H. S. Teoh via Digitalmars-d]

On Fri, Jan 23, 2015 at 05:34:28PM +0000, aldanor via Digitalmars-d wrote:
> 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.

That's not a problem; post your ideas / drafts here and I'm sure you'll
get lots of feedback and improvement suggestions.


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

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.


[...]
> >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.

I vote for ddoc / static generation. The site itself is static anyway,
using client-side JS to do this seems to be overkill.


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


T

-- 
Give a man a fish, and he eats once. Teach a man to fish, and he will sit forever.