Hi everyone,
I decided to give D a try yesterday and had quite some trouble with the
documentation. I want to help improve the docs on dlang.org. Here are
some ideas.
The top links in the left menu really should documentation. Most people
don't care about Acknowledgements, the Sitemap, D1, D2 changelog etc.
What do you guys think about a navigation like this?
* About D
- Features (list of features with syntax examples)
- Why D (motivation/rationale, comparison, testimonials, ...)
* Documentation
- Book (link to Amazon)
- Language Reference [1]
- Library Reference [2]
* Community [3]
* Development [4]
[1] The Language Reference is pretty good already but I think the formal
grammar specifications should be replaced with syntax examples. You
don't learn a language's grammar by studying it in EBNF (or whatever)
but by looking at code. We could still keep the specs at the bottom of
the pages.
[2] Not much to complain here; I'd just group the modules by topic
rather than alphabetically -- e.g. "Base" (array, algorithm, date/time,
path, regex, string, I/O, functional), "Math", "Network",
"Processes/Concurrency", "Formats" (compression/archives, json, ...),
"Platforms", "Contracts/Traits", ...
[3] A link to the mailman site. I believe most developers have organized
their workflow around email.
[4] That's where we can stick all the stuff I proposed to get rid of on
top of the navigation (changelog, ack. etc)
I'd like to get some feedback on these ideas. If you like them, I'm
happy to send some pull requests implementing the changes.
Jonas
