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.
