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.

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!

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

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

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

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.

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.

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

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.

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.