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

H. S. Teoh via Digitalmars-d digitalmars-d at puremagic.com
Fri Jan 23 09:17:23 PST 2015


On Fri, Jan 23, 2015 at 05:03:15PM +0000, aldanor via Digitalmars-d wrote:
[...]
> 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. Our current documentation is *reference* documentation, i.e.,
something you look stuff up in *after* you've learned the language. It's
not suitable for a tutorial or getting-started guide. We need more of
those!

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


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

Yeah I've run into the same problem. Google search does not eliminate
the need for a proper, well-thought-out, navigable index.


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

Actually, this has annoyed me so much that I've completely nuked the
page in Phobos git HEAD, and replaced it with something hopefully more
useful. You can see this new page under the prerelease tab:

	http://dlang.org/phobos-prerelease/index.html

So hopefully, by the next release, we will no longer be plagued by
complaints about the current leading page.


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

I'm thinking perhaps an autogenerated alphabetical index of all symbols
might be in order here?


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

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.


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

If you're not happy with Ali's book, please contribute your own. I'm
pretty sure the dlang.org maintainers will be more than glad to include
it.


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

Would you like to step up and spearhead this effort?


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

Good! So let's see the PR's. :-)


T

-- 
Stop staring at me like that! It's offens... no, you'll hurt your eyes!


More information about the Digitalmars-d mailing list