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

On 4/8/12 7:41 AM, Jonas H. wrote:
> 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.

I'm generally in favor of simplifying the sidebar navigation, since I already did a bunch of that under the guise of creating a new look for the D website :)  Compare with the sidebar at http://digitalmars.com/d/1.0/index.html

I think you may find some conflicts between the contents of the proposed Development and the existing Community sections; that probably needs some further thought.

As a technical note, in order to get the sidebar to expand correctly you'll need to change the CATEGORY_* macro on any pages that you move. For instance, if you were to hypothetically move a page from being under the Articles section to being under the FAQ section, you'd need to change its CATEGORY_ARTICLES=$0 macro to CATEGORY_FAQ=$0.