Rant after trying Rust a bit

[H. S. Teoh via Digitalmars-d]

On Thu, Jul 23, 2015 at 04:54:50PM +0000, jmh530 via Digitalmars-d wrote:
[...]
> I see that now. It's there, but it's practically a throw-a-way line.
> I've looked at that page a bunch of times and skipped over it each
> time. This is a broader problem with D's reference pages.
> 
> Compare
> http://dlang.org/interface.html
> with
> https://doc.rust-lang.org/book/traits.html
> which is better?
> 
> Rust's documentation uses clear examples to show how something should
> be used and the most important features. By contrast, there are many
> parts of D's documentation that someone with less-than-expert
> programming knowledge will find quite difficult to understand.
> 
> For instance, look at http://dlang.org/function.html you have to
> scroll down for quite a while before you even get to anything useful.
> Then, what's the first thing that comes up? Something about contracts,
> return values, bodies, purity. Not "this is what a D function is".
> 
> I'm all for a complete reference of every D feature, but there needs
> to be some step up in terms of difficulty of the material. Start with
> the basics, then work up into all the specifics. I'd say at a minimum
> some of this documentation needs to be broken up into several pages.
> 
> There seem to be a lot of places where I could improve the D
> documentation.  However, I feel like if I start going crazy with
> changes I might get some push-back...
[...]

Please bring on the PR's, we need all the help we can get!

As for push-back... as long as each PR is focused on one thing, e.g.,
improving the prose, or adding a beginner-friendly example to the top of
the page, I think it will be acceptable. Just don't put too many changes
into one PR (reformat the source, fix whitespace, rewrite 5 disparate
paragraphs, etc., you know what I mean).


T

-- 
Notwithstanding the eloquent discontent that you have just respectfully expressed at length against my verbal capabilities, I am afraid that I must unfortunately bring it to your attention that I am, in fact, NOT verbose.