www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - dlang.org redesign -- the state of documentation and learning

reply "aldanor" <i.s.smirnov gmail.com> writes:
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.
Jan 23 2015
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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!
Jan 23 2015
parent reply "aldanor" <i.s.smirnov gmail.com> writes:
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.

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.


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



 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.


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


I (personally) am happy with Ali's book of course! But as I've 
already said a link to the book != a proper _official_ 
introduction. It could largely overlap though, that's true.


 Would you like to step up and spearhead this effort?


Not alone by myself, that's for sure :) Ideally, someone who's 
already done a considerable amount of work on a book / docs, of 
course...


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


This needs to be well thought through :) But if noone objects to 
the style of "Rust by Example" which I tend to like -- perhaps we 
could come up with something similar (and perhaps more 
interesting, especially when it gets to all the metaprogramming 
jazz).
Jan 23 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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.
Jan 23 2015
parent reply "aldanor" <i.s.smirnov gmail.com> writes:
On Friday, 23 January 2015 at 18:17:30 UTC, H. S. Teoh wrote:

 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.


Agreed. I think that's exactly the target audience (and exactly 
the one that we are missing the proper docs/guide for). After 
all, D is not a "learn me a ruby in 15 minutes" kind of language, 
so the chances are whoever's coming here has a vague idea of what 
they expect or what they want to learn about D. Just as an 
example, I've heard a lot of D talk on #rust-offtopic irc -- 
those folks would barely qualify as beginner programmers.


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


You need both. What I meant was that DDOC has to be able to 
generate an index (one huge dict) and store that in a text 
file/json. The client-side would just use that "database" to 
provide on-site incremental search. Quite easy.


 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.


Thanks for clarifying. I too hope this thread doesn't just become 
another bikeshedding timesink :) I'll get some style-related 
drafts published on the weekend and then we'll see how it goes 
from there. Indeed, I won't mind to "spearhead" this (if I knew 
how!) since the whole documentation story is very sad, provides D 
with negative publicity and provides users like us with constant 
annoyance (but... it can be fixed -- we all know it).
Jan 23 2015
parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Fri, Jan 23, 2015 at 06:30:04PM +0000, aldanor via Digitalmars-d wrote:

 On Friday, 23 January 2015 at 18:17:30 UTC, H. S. Teoh wrote:


[...]

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


 You need both. What I meant was that DDOC has to be able to generate
 an index (one huge dict) and store that in a text file/json. The
 client-side would just use that "database" to provide on-site
 incremental search. Quite easy.


I wouldn't mind just generating a static index and putting it on an
index page somewhere. I'm not against using JS for stuff like this, but
generally I prefer static navigation. (But that's just me. I know I'm in
the minority. :-P)


[...]

 Thanks for clarifying. I too hope this thread doesn't just become
 another bikeshedding timesink :) I'll get some style-related drafts
 published on the weekend and then we'll see how it goes from there.
 Indeed, I won't mind to "spearhead" this (if I knew how!)


It's not that hard. Just start submitting PRs and pointing people to it.
Make enough noise about it and people are bound to notice. If your idea
has any merit (and I think it does) people should follow suit.



 since the whole documentation story is very sad, provides D with
 negative publicity and provides users like us with constant annoyance
 (but...  it can be fixed -- we all know it).


Of course it can be fixed -- what *can't* programmers fix? (Besides the
halting problem, that is. :-P) It's just a matter of someone stepping up
to the plate and actually *doing* something about it.

Besides, Andrei has even offered to write the content -- you have
preapproval even before you ask for it! If I were you, I'd charge full
steam ahead!


T

-- 
The easy way is the wrong way, and the hard way is the stupid way. Pick one.
Jan 23 2015
prev sibling next sibling parent "aldanor" <i.s.smirnov gmail.com> writes:
On Friday, 23 January 2015 at 17:03:17 UTC, aldanor wrote:

 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 turns out that's exactly how it's done on the rust website, 
poor man's index engine :)

http://doc.rust-lang.org/search-index.js -- DDOC can totally 
generate something like this, just a huge dict of markers. Once 
this is done, the client-side is quite easy.
Jan 23 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/23/15 9:03 AM, aldanor wrote:

 [NB] SUGGESTION: initiate work on an Official Guide and keep it up to
 date with the latest language features.


That would be fantastic, and something that might be parallelizable as 
well. Here's a related thought: I wonder what it would take to put 
together a nice slideshow-style progression, with editable code snippets 
and stuff. Then I'd be happy to work on the content. -- Andrei
Jan 23 2015
parent reply "aldanor" <i.s.smirnov gmail.com> writes:
On Friday, 23 January 2015 at 18:00:13 UTC, Andrei Alexandrescu 
wrote:

 On 1/23/15 9:03 AM, aldanor wrote:

 [NB] SUGGESTION: initiate work on an Official Guide and keep 
 it up to
 date with the latest language features.


 That would be fantastic, and something that might be 
 parallelizable as well. Here's a related thought: I wonder what 
 it would take to put together a nice slideshow-style 
 progression, with editable code snippets and stuff. Then I'd be 
 happy to work on the content. -- Andrei


What do you mean by a slideshow style progression? Would you have 
an example? I thought of something simple 
http://rustbyexample.com/ as a guideline, but hosted officially 
on dlang.org and being part of the website. Is that close?

/* don't worry much about implementing the cool client-side UI 
stuff if that's what you mean, whatever it is, it's all doable 
(or, in all likelihood, it has already been done in a form of 
some js library) and it normally only takes one person to 
integrate it it; writing a cohesive exciting (!) user guide 
though is a big undertaking and responsibility. As you said 
though, it can be highly parallelizable! */
Jan 23 2015
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/23/15 10:09 AM, aldanor wrote:

 On Friday, 23 January 2015 at 18:00:13 UTC, Andrei Alexandrescu wrote:

 On 1/23/15 9:03 AM, aldanor wrote:

 [NB] SUGGESTION: initiate work on an Official Guide and keep it up to
 date with the latest language features.


 That would be fantastic, and something that might be parallelizable as
 well. Here's a related thought: I wonder what it would take to put
 together a nice slideshow-style progression, with editable code
 snippets and stuff. Then I'd be happy to work on the content. -- Andrei


 What do you mean by a slideshow style progression? Would you have an
 example? I thought of something simple http://rustbyexample.com/ as a
 guideline, but hosted officially on dlang.org and being part of the
 website. Is that close?


Both are nice:

http://tour.golang.org/welcome/1
http://rustbyexample.com/


 /* don't worry much about implementing the cool client-side UI stuff if
 that's what you mean, whatever it is, it's all doable (or, in all
 likelihood, it has already been done in a form of some js library) and
 it normally only takes one person to integrate it it; writing a cohesive
 exciting (!) user guide though is a big undertaking and responsibility.
 As you said though, it can be highly parallelizable! */


I can get cranked on that. Just give me the ddoc macros to fill.


Andrei
Jan 23 2015
parent reply =?UTF-8?B?TWFydGluIERyYcWhYXI=?= via Digitalmars-d writes:
Dne 23.1.2015 v 19:16 Andrei Alexandrescu via Digitalmars-d napsal(a):

 Both are nice:
=20
 http://tour.golang.org/welcome/1
 http://rustbyexample.com/


Or something along the lines of https://tryhaskell.org
With possible integration with D REPL.
Jan 23 2015
parent "Martin Nowak" <code dawg.eu> writes:
On Friday, 23 January 2015 at 18:37:07 UTC, Martin DraĊĦar wrote:

 Dne 23.1.2015 v 19:16 Andrei Alexandrescu via Digitalmars-d 
 napsal(a):

 Both are nice:
 
 http://tour.golang.org/welcome/1
 http://rustbyexample.com/


 Or something along the lines of https://tryhaskell.org
 With possible integration with D REPL.


That's actually where I want to go with D REPL.
Even more interesting would be user editable tutorials.
As usual lacking the time for this right now.
Jan 31 2015
prev sibling next sibling parent reply "Zach the Mystic" <reachzach gggmail.com> writes:
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!
Jan 23 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Fri, Jan 23, 2015 at 09:20:10PM +0000, Zach the Mystic via Digitalmars-d
wrote:
[...]

 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!


Let's see the PR! ;-)


T

-- 
Democracy: The triumph of popularity over principle. -- C.Bond
Jan 23 2015
parent reply "Zach the Mystic" <reachzach gggmail.com> writes:
On Friday, 23 January 2015 at 21:56:59 UTC, H. S. Teoh wrote:

 On Fri, Jan 23, 2015 at 09:20:10PM +0000, Zach the Mystic via 
 Digitalmars-d wrote:
 [...]

 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!


 Let's see the PR! ;-)


 T


Consider me destroyed! I mean to get started with it, but it'll 
take a week or so.
Jan 24 2015
parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Sat, Jan 24, 2015 at 06:51:08PM +0000, Zach the Mystic via Digitalmars-d
wrote:

 On Friday, 23 January 2015 at 21:56:59 UTC, H. S. Teoh wrote:

On Fri, Jan 23, 2015 at 09:20:10PM +0000, Zach the Mystic via
Digitalmars-d wrote:
[...]

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!


Let's see the PR! ;-)


T


 
 Consider me destroyed! I mean to get started with it, but it'll take a
 week or so.


A week is a short time as far as D pull requests go. :-P

Also, incremental is the key. Don't bite off more than you can chew.
Start with a barebones skeletal version of what you envision. Make it
work, then submit the PR. Let others build upon it.


T

-- 
Indifference will certainly be the downfall of mankind, but who cares? --
Miquel van Smoorenburg
Jan 24 2015
next sibling parent "Zach the Mystic" <reachzach gggmail.com> writes:
On Saturday, 24 January 2015 at 18:59:52 UTC, H. S. Teoh wrote:

 On Sat, Jan 24, 2015 at 06:51:08PM +0000, Zach the Mystic via 
 Digitalmars-d wrote:

 Consider me destroyed! I mean to get started with it, but 
 it'll take a
 week or so.


 A week is a short time as far as D pull requests go. :-P

 Also, incremental is the key. Don't bite off more than you can 
 chew.
 Start with a barebones skeletal version of what you envision. 
 Make it
 work, then submit the PR. Let others build upon it.


 T


Right on.
Jan 24 2015
prev sibling parent "Zach the Mystic" <reachzach gggmail.com> writes:
On Saturday, 24 January 2015 at 18:59:52 UTC, H. S. Teoh wrote:

 On Sat, Jan 24, 2015 at 06:51:08PM +0000, Zach the Mystic via 
 Digitalmars-d wrote:

 On Friday, 23 January 2015 at 21:56:59 UTC, H. S. Teoh wrote:

On Fri, Jan 23, 2015 at 09:20:10PM +0000, Zach the Mystic via
Digitalmars-d wrote:
[...]

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!


Let's see the PR! ;-)


T


 
 Consider me destroyed! I mean to get started with it, but 
 it'll take a
 week or so.


 A week is a short time as far as D pull requests go. :-P

 Also, incremental is the key. Don't bite off more than you can 
 chew.
 Start with a barebones skeletal version of what you envision. 
 Make it
 work, then submit the PR. Let others build upon it.


 T


Here it is, T:

https://github.com/D-Programming-Language/dlang.org/pull/878

https://issues.dlang.org/show_bug.cgi?id=14088

I think we should make the Wiki the first place beginners should 
go. It's quite a step ahead of the dlang.org website. We should 
transfer all the articles on dlang to the Wiki, IMO.

Just look at how clunky and old some of dlang is compared to the 
Wiki. There seems to be a huge rift between the advantages of 
using DDoc to keep code documentation up to date, and the 
advantages of the easily and instantly edited Wiki. Looking at 
the two sites, the Wiki is the clear winner for anything except 
the language and library reference... and it could eventually be 
the winner even on those, with enough people editing without the 
burden of code review or Ddoc's learning curve.
Jan 30 2015
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 1/23/15 9:03 AM, aldanor wrote:

 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.


[snip]

These insights are solid, sorry for not explicitly stating my position 
earlier.

My suggestion for these ideas to materialize is to initiate pull 
requests for everything that is a net improvement on the state of 
affairs, and create issues for the larger items that need more 
collaborators or longer spans of work. I will preapprove appropriately.

Incremental is key here. Of this list of desirable things, what is one 
thing that could be done now and result in a better site? For example 
Panke updated wc.dd. Now we're in a better place than before, even if 
say in a month's time we decide to replace the example completely.

I restate: if you provide me a simple way to fill a step-by-step 
tutorial, I'll happily do it.


Andrei
Jan 23 2015
prev sibling next sibling parent reply "weaselcat" <weaselcat gmail.com> writes:
On Friday, 23 January 2015 at 17:03:17 UTC, aldanor wrote:

 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


you mean like this?
https://qznc.github.io/d-tut/index.html
Jan 23 2015
parent "Jerry Morrison" <jhm456 gmail.com> writes:
After spending hours and hours in a breadth-first scan to learn 
me a D, I agree completely with the suggestions in this thread 
and I'm happy to help implement them.

Caveats: I'm just now coming up to speed on D and I'm an 
engineer, not a tech writer.

I think the biggest needs are:

(1) Improve the home page "Why pick D?" info. The current text 
doesn't quite answer. Why switch from your creaky old language? 
And if you're switching, why D vs. Rust?

Mention the game-changing plans for optional GC, memory safety, 
and calling C++. Then D becomes a clear win in real-time, 
safety-critical, and security-critical systems.

(2) Add an introduction for experienced C++/Java programmers. Get 
them up to speed quickly and excited about how D is easier, 
faster, more fun, more reliable, and un-fsck'd up.

(3) [Easy] Add comparative info to the links to available books, 
including the D reference: Aim? Audience? Up to date? Coverage?

Ali's ebook is very nice but for beginning programmers, not me. 
(Ali, you might want to say so up front.) Andrei's book is 4.6 
years old. How much has D changed? Honestly I'm a slow reader and 
will eventually read the spec, so I started reading that. Is that 
a rough way to start? Too many forward references? Too abstract? 
What'll I miss by not reading a book first (besides Andrei's 
humor)?

*If y'all shed light on the books, I'll update the wiki* 
http://wiki.dlang.org/Books

Note: This page doesn't jive with 
http://digitalmars.com/d/dlinks.html

(4) [Easy] Add more info on the available IDEs: Up to date? 
Graphical debugger? Features? Maintained? Recommended?

I'm currently using Sublime text but need my graphical debugger 
so I'll try Eclipse + DDT soon. I could try Visual D but I'm 
expecting to move off Windows. A good IntelliJ plug-in would be 
ideal.

*Tell me about the IDEs and I'll update the wiki* 
http://wiki.dlang.org/IDEs


On Saturday, 24 January 2015 at 04:35:27 UTC, weaselcat wrote:

 you mean like this?
 https://qznc.github.io/d-tut/index.html


Sort of, but it's old and says little about the language itself.
Jan 23 2015
prev sibling parent reply Andrej Mitrovic via Digitalmars-d <digitalmars-d puremagic.com> writes:
On 1/23/15, aldanor via Digitalmars-d <digitalmars-d puremagic.com> wrote:

 In continuing the series of rant posts about the website, this
 one will be about the documentation.


Excellent points. In fact this kind of feedback is exactly what we
need, to learn what it's like for someone new who just visits the
website and tries D out. There are some things us regulars are taking
for granted these days.

Here's another one:

The search box allows selecting between:
- Entire D Site
- Library reference
- Newsgroup archives

But where's the Language spec option?

I'm ashamed to admit when I really want to find a link to a specific
spec page (e.g. to point someone new to some relevant docs) I end up
grepping through the dlang.org .dd files instead, and then figure out
on which page something is located at.
Jan 25 2015
parent reply David Gileadi <gileadis NSPMgmail.com> writes:
On 1/25/15 4:42 AM, Andrej Mitrovic via Digitalmars-d wrote:

 Here's another one:

 The search box allows selecting between:
 - Entire D Site
 - Library reference
 - Newsgroup archives

 But where's the Language spec option?


It's missing due to how dlang.org is set up, and the limitations of 
Google's site search feature. If you click on a link in the language 
spec, like on Types, you'll notice that its URL has the page directly 
under dlang.org, e.g. http://dlang.org/type.html.

In contrast, the standard library is in a subfolder (e.g. 
http://dlang.org/phobos/std_algorithm.html) and the newsgroup archives 
are in another subfolder. Being in a subfolder allows us to pass a 
prefix parameter to Google's site search that will limit its results to 
URLS with that prefix. Since the language reference isn't in a subfolder 
there's no prefix for the language reference that doesn't also include 
everything else in the site, and hence there's no option for Language Spec.

I don't know how hard it would be to put all the language spec pages 
into their own subfolder, but doing so would allow us to add the 
Language Spec option to the dropdown.
Jan 26 2015
parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Mon, Jan 26, 2015 at 09:48:34AM -0700, David Gileadi via Digitalmars-d wrote:

 On 1/25/15 4:42 AM, Andrej Mitrovic via Digitalmars-d wrote:

Here's another one:

The search box allows selecting between:
- Entire D Site
- Library reference
- Newsgroup archives

But where's the Language spec option?


 
 It's missing due to how dlang.org is set up, and the limitations of
 Google's site search feature. If you click on a link in the language
 spec, like on Types, you'll notice that its URL has the page directly
 under dlang.org, e.g. http://dlang.org/type.html.
 
 In contrast, the standard library is in a subfolder (e.g.
 http://dlang.org/phobos/std_algorithm.html) and the newsgroup archives
 are in another subfolder. Being in a subfolder allows us to pass a
 prefix parameter to Google's site search that will limit its results
 to URLS with that prefix. Since the language reference isn't in a
 subfolder there's no prefix for the language reference that doesn't
 also include everything else in the site, and hence there's no option
 for Language Spec.
 
 I don't know how hard it would be to put all the language spec pages
 into their own subfolder, but doing so would allow us to add the
 Language Spec option to the dropdown.


It shouldn't be too hard. Except it will require some HTTP redirects so
that existing incoming links won't unduly break. There has already been
PRs for reorganizing the files at the top level of the dlang.org repo.


T

-- 
Knowledge is that area of ignorance that we arrange and classify. -- Ambrose
Bierce
Jan 26 2015