www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Documentation improvements

reply "Jonas H." <jonas lophus.org> writes:
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
Apr 08 2012
parent David Gileadi <gileadis NSPMgmail.com> writes:
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.
Apr 09 2012