www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - dlang.org "Getting Started" page

reply "Zach the Mystic" <reachzach gggmail.com> writes:
I'm looking for feedback for:

https://github.com/D-Programming-Language/dlang.org/pull/878
https://issues.dlang.org/show_bug.cgi?id=14088

Investigation shows that the D Wiki is the best landing place for 
newcomers, so they are directed there first. I think the current 
page leaves newcomers a little bit stranded.
Jan 31 2015
parent reply "Jonathan Marler" <johnnymarler gmail.com> writes:
On Saturday, 31 January 2015 at 19:03:55 UTC, Zach the Mystic 
wrote:

 I'm looking for feedback for:

 https://github.com/D-Programming-Language/dlang.org/pull/878
 https://issues.dlang.org/show_bug.cgi?id=14088

 Investigation shows that the D Wiki is the best landing place 
 for newcomers, so they are directed there first. I think the 
 current page leaves newcomers a little bit stranded.



Seems like a good idea to me.  One thought, when I'm looking at a 
new language and I see a "Getting Started", I would expect to see 
links for tutorials such as how to install and tutorials on 
writing Hello World...  I would put those links first.
Jan 31 2015
parent reply "Zach the Mystic" <reachzach gggmail.com> writes:
On Saturday, 31 January 2015 at 19:22:06 UTC, Jonathan Marler 
wrote:

 On Saturday, 31 January 2015 at 19:03:55 UTC, Zach the Mystic 
 wrote:

 I'm looking for feedback for:

 https://github.com/D-Programming-Language/dlang.org/pull/878
 https://issues.dlang.org/show_bug.cgi?id=14088

 Investigation shows that the D Wiki is the best landing place 
 for newcomers, so they are directed there first. I think the 
 current page leaves newcomers a little bit stranded.



 Seems like a good idea to me.  One thought, when I'm looking at 
 a new language and I see a "Getting Started", I would expect to 
 see links for tutorials such as how to install and tutorials on 
 writing Hello World...  I would put those links first.


In principle, I agree, but the front page of the Wiki has such 
links already, plus a whole lot more. It won't take the new user 
long to find what they're looking for there.

I thought "Getting Started" was a good title, but maybe I should 
change it to "Introduction".
Jan 31 2015
next sibling parent "Zach the Mystic" <reachzach gggmail.com> writes:
On Saturday, 31 January 2015 at 19:35:45 UTC, Zach the Mystic 
wrote:

 On Saturday, 31 January 2015 at 19:22:06 UTC, Jonathan Marler 
 wrote:

 Seems like a good idea to me.  One thought, when I'm looking 
 at a new language and I see a "Getting Started", I would 
 expect to see links for tutorials such as how to install and 
 tutorials on writing Hello World...  I would put those links 
 first.


 In principle, I agree, but the front page of the Wiki has such 
 links already, plus a whole lot more. It won't take the new 
 user long to find what they're looking for there.

 I thought "Getting Started" was a good title, but maybe I 
 should change it to "Introduction".


"Introduction" would conflict with: http://dlang.org/intro.html
I think that's why I avoided it. If you've got something better, 
please suggest.
Jan 31 2015
prev sibling parent reply "Jonathan Marler" <johnnymarler gmail.com> writes:
On Saturday, 31 January 2015 at 19:35:45 UTC, Zach the Mystic 
wrote:

 On Saturday, 31 January 2015 at 19:22:06 UTC, Jonathan Marler 
 wrote:

 On Saturday, 31 January 2015 at 19:03:55 UTC, Zach the Mystic 
 wrote:

 I'm looking for feedback for:

 https://github.com/D-Programming-Language/dlang.org/pull/878
 https://issues.dlang.org/show_bug.cgi?id=14088

 Investigation shows that the D Wiki is the best landing place 
 for newcomers, so they are directed there first. I think the 
 current page leaves newcomers a little bit stranded.



 Seems like a good idea to me.  One thought, when I'm looking 
 at a new language and I see a "Getting Started", I would 
 expect to see links for tutorials such as how to install and 
 tutorials on writing Hello World...  I would put those links 
 first.


 In principle, I agree, but the front page of the Wiki has such 
 links already, plus a whole lot more. It won't take the new 
 user long to find what they're looking for there.

 I thought "Getting Started" was a good title, but maybe I 
 should change it to "Introduction".


Personally, when I get started with a new language the first 
things I want are:

1. Examples (Hello World, File IO, some examples that demonstrate 
what makes the language unique).

2. I want to see an introduction to the language, what makes the 
language unique, what are the goals of the language, things like 
that.

3. I want to see language references, where can I go to reference 
how to do something in the language.

4. I want to see build/install/small program tutorials.


I think these 4 things should require 1 click to get to.  The 
user should be able to click on one link ("Getting Started") is a 
good name, and then be able to see direct links to all these 
topics.  Redirecting to a wiki is not horrible but I think the 
optimal design is to have one landing page that a user can go 
back to in order to get started and find everything they need.  
In our case, I think links to the wiki and forums would be good 
as well, but the most important things should be obvious and easy 
to get to.  Splitting these topics up among the wiki and the 
dlang website makes it harder to get around, not horrible, but 
not optimal.
Jan 31 2015
parent "Zach the Mystic" <reachzach gggmail.com> writes:
On Saturday, 31 January 2015 at 21:05:27 UTC, Jonathan Marler 
wrote:

 Personally, when I get started with a new language the first 
 things I want are:

 1. Examples (Hello World, File IO, some examples that 
 demonstrate what makes the language unique).


Currently on the front page, dlang.org.


 2. I want to see an introduction to the language, what makes 
 the language unique, what are the goals of the language, things 
 like that.


Ditto.


 3. I want to see language references, where can I go to 
 reference how to do something in the language.


The buttons for the language and library references are right 
below Getting Started. They can't be easier to locate than they 
currently are. Other articles of this sort are scattered 
everywhere, both on and off the official websites.


 4. I want to see build/install/small program tutorials.

 I think these 4 things should require 1 click to get to.  The 
 user should be able to click on one link ("Getting Started") is 
 a good name, and then be able to see direct links to all these 
 topics.  Redirecting to a wiki is not horrible but I think the 
 optimal design is to have one landing page that a user can go 
 back to in order to get started and find everything they need.  
 In our case, I think links to the wiki and forums would be good 
 as well, but the most important things should be obvious and 
 easy to get to.  Splitting these topics up among the wiki and 
 the dlang website makes it harder to get around, not horrible, 
 but not optimal.


IMO, the most important thing *is* the Wiki, but a newcomer might 
not know that, so they must be told. If I try to decide the best 
link for them I'll just be duplicating the effort done on the 
Wiki page.

Just send people to the Wiki. It has the best current information 
about what to do and where to go. I think the Wiki should be the 
official place to go to get information on D. Dlang.org should be 
concise and formal, containing only the most permanent 
information. D doesn't have a wealthy funder to pay for building 
a single unified website experience. It needs to leverage the 
community instead.

The proof is already there - The Wiki is currently the best place 
to go for information about D. In fact, I didn't even know that 
it was the best place until I was trying to figure out how to 
improve dlang.org, and realized I would just be duplicating the 
effort done on the Wiki. Yes, the Wiki could be made better, and 
it will, because editing is easy and unburdened by the review 
process. I just made a few edits myself.

I'm follow the evidence. Dlang.org should say, regarding the 
Wiki, "If you can't beat 'em, join 'em." And by referring people 
there to begin with, more effort will be put into it. And yes, I 
am advocating continuing the weird competition between Ddoc and 
other markup languages. Would it be great if Wiki markup and Ddoc 
were completely compatible? Yes, so people could learn Ddoc at 
the same time as editing the Wiki. But as I said, the evidence is 
in the outcome. Please compare the Wiki to dlang.org. I don't 
think dlang.org can keep up.

That said... we should copy look-and-feel from dlang to the Wiki, 
so it won't feel like so much of a defeat!
Feb 01 2015