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

Zach the Mystic via Digitalmars-d digitalmars-d at puremagic.com
Fri Jan 23 13:20:10 PST 2015


On Friday, 23 January 2015 at 17:03:17 UTC, aldanor wrote:
> 1) D Learning
>
> This is the most problematic part. It's not even obvious where 
> to start.
>
> Say I just landed on dlang.org via a google search and I want 
> to find a quick user guide. I click D Reference (that seems the 
> closest one to "beginner's guide" out of all options) and I see 
> an "Introduction" page. Ok, looks promising, what do we have 
> there... Ouch, Phases of Compilation, that went wrong fast. 
> Let's try the next one, Lexical. Ouch, wall of text composed of 
> ascii characters, unicode escapes and all other boring things.
>
> Let's go back to Books & Articles. Now, Ali's book is sure very 
> nice, but it's way overly detailed for introduction as it's 
> trying to miss a single thing (which is sure a good thing! ... 
> that is, if you actually decide on reading a BOOK in a first 
> place). Plus, it's not on dlang.org so it doesn't feel 
> "official". Going back to more books, we see some 5-7 year old 
> books, some very recent ones (but not free), and a few 
> tutorials on a specific areas (like Philip's) -- again, nothing 
> really qualifies as an introduction guide. This section is 
> definitely more well-suited for intermediate D programmers who 
> already know what they want to learn.
>
> Books & Articles -> Howtos (is that a book or an article?). 
> This links to a wiki.dlang.org (yet another site?..) where we 
> have an unorganized mess of links. Some of them sound useful 
> but it's unlikely we are interested in voldemort types or 
> unittest placement yet. In fact, I've just found out there's a 
> bunch of information on wiki that I see myself for the first 
> time -- if it took me several years, how long will it take a 
> newcomer? It would be nice to move the best/finalized bits and 
> examples into a sort of a "D by Example" official section on 
> the website. Wiki is useful as a collaborative sandbox or a 
> staging area, but it's fugly, feels foreign and not so nice for 
> reading.
>
> ... that's all. At this point the disgruntled newbie closes the 
> dlang.org website and goes on learning himself some Rust.
>
> [NB] SUGGESTION: initiate work on an Official Guide and keep it 
> up to date with the latest language features. It could even be 
> largely a copy-paste from Ali's book and TDPL (upon Ali's and 
> Andrei's permission), omitting unnecessary details (and rather 
> pointing at a specific places in documentation where additional 
> information could be found) and written in a friendly manner 
> with a human touch. I think it's much simpler than it sounds if 
> we do it collaboratively and it doesn't have to be 
> feature-complete before released. If we choose to do it, it may 
> be best to keep it in a separate github repo in order to make 
> it easier to compile separately without having to compile 
> dmd/druntime/etc.
>
> Optionally, but highly suggested: initiate work on D by 
> Example: a searchable collection of up-to-date self-documenting 
> D examples, structured by the topic, like a book. Some of the 
> examples from wiki could be moved there, some Rosetta examples 
> by bearophile and many more. Could be even parts of some 
> libraries or Phobos. The point is, we have more than we need, 
> it's just scattered across the Internet, so we need to 
> unscatter it.

I have a basic suggestion on how to get started. Create a 
"Learning D" button and put it on the menu at left on the front 
page. On the page it links to, start by researching and listing 
every existing resource for learning D, in a "kitchen sink" kind 
of way. Now future contributors can know what already exists, and 
what doesn't. The importance of this list is that anyone wanting 
to help create new teaching aids can quickly get up to speed on 
the current state of affairs. They can feel assured that they're 
not duplicating anyone else's work. As the official list and 
accessible from the front page, it's more likely to be kept up to 
date. The point is that it serves double duty both as a treasure 
trove of learning links, and as a complete reference for future 
contributors. Destroy, please!


More information about the Digitalmars-d mailing list