|Posted by Jonas H.||PermalinkReply|
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, ...)
- Book (link to Amazon)
- Language Reference 
- Library Reference 
* Community 
* Development 
 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.
 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", ...
 A link to the mailman site. I believe most developers have organized their workflow around email.
 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.