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.
