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

[aldanor via Digitalmars-d]

In continuing the series of rant posts about the website, this 
one will be about the documentation. This is a big one and no 
fixing css or pretty menus can amend this.

I've recently started learning Rust myself (a few weeks ago) and 
despite the alpha state of both rustc and rust-lang.org website, 
I found it great and exciting to learn the language. There is a 
well-thought-out official guide that was a breeze to read through 
-- I've read most of it while commuting to work on my phone. Then 
there's Rust by Example which is essentially a semi-organized 
collection of how-tos, gotchas, snippets and code samples. Rust 
is not the easiest language of all to learn, but they try to make 
it simple for those who try.

On the bright side, D has a book. Or rather, it has THE book and 
a few more books, some of which are free and some are not. 
However, I wouldn't ever start to read a 500-page manuscript just 
in order to get acquainted with the language and poke around. 
There needs to be an official Guide that is not too overly 
detailed and written in an easy language.

To give a few examples:
- http://doc.rust-lang.org/book/
- https://www.ruby-lang.org/en/documentation/quickstart/
- http://ocaml.org/learn/tutorials/basics.html

I personally see "learning" and "documentation" as two different 
classes of information. Learning resources might include 
tutorials, code examples, articles, books, whereas documentation 
would be a place for more formal (and sometimes 
computer-generated) information on the standard library, API 
reference, language grammar and maybe an official style guide. 
Ideally, the Learning section would be sufficient for a rookie to 
get started and that should be the go-to destination for all 
newcomers.

1.1) Documentation: D Reference

Is very hard to browse or search. I don't remember how many times 
I was looking for an "is" statement docs only to find again, 
buried under <h4>IsExpresssion</h4> in expression.html, a dozen 
of pages scrolling down from top. There are no TOCs in the files, 
there is no global TOC, the drop-down menu on the left is 
extremely long and non-nested and takes one screen vertically.

All in all though, the contents are OK -- it does require some 
polishing, it needs to be properly indexed and laid out but 
that's doable without changing the contents much.

1.2) Documentaiton: Standard Library

There's been some good progress on it recently by Andrei -- but 
it's auto-generated for the most part so the most of work is in 
hacking ddoc and styling. The only two issues I could point out 
is the landing page for "Standard Library" -- I would expect to 
see a structure of D's stdlib or a nice index and quick links 
rather than a "why this and why that" wall of text (which should 
stay as a separate page, but not as an entry point to the 
standard library pages, from the usability point of view). 
Another point: there needs to be a better on-site search. 
Apologies for mention Rust again, but: 
http://doc.rust-lang.org/std/index.html (type S, see what happens 
-- the search is not perfect but it's incremental and you can 
search for functions/traits separately). Since we are the ones 
who generate the docs, we can totally do this (in a simplest way, 
bake in the markers into the ddoc and generate a javascript 
hashmap to trace back to them).

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.

Books & Articles -> Floating Point. What does that article have 
to do with learning D and what exactly is it doing there (apart 
from being a nice article on floating point)?

Example: wc -> this is neither a book, nor an article and it 
belongs to a "D by Example" along with other examples from wiki. 
Plus, the code is quite ugly and inelegant.

Warnings: not a book nor an article. Belongs in Documentation.

C to D: this is especially confusing, since there are:
- Books & Articles > C to D
- Books & Articles > C++ to D
- Books & Articles > C Preprocessor to D
- D Reference > Interfacing to C
- D Reference > Interfacing to C++
which overlap somewhat (the "Books & Articles" ones) being more 
of a collection of recipes without a proper index. Quite hard to 
browse through or search for something specific. Not sure if this 
belongs to Learning or Documentation, perhaps the latter.

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