Here's looking at you, kid

[Warwick via Digitalmars-d]

On Sunday, 15 November 2015 at 11:46:54 UTC, Saurabh Das wrote:
> On Friday, 13 November 2015 at 22:34:18 UTC, Andrei 
> Alexandrescu wrote:
>> Hi everyone,
>>
>>
>> Recently there's been an uptick of site visits on dlang.org 
>> and also dmd downloads 
>> (http://erdani.com/d/downloads.daily.png).
>>
>> Amid increased scrutiny it's important to focus on improving 
>> documentation. I suggest everyone in the community to consider 
>> improving dlang.org in any way. For Phobos in particular, the 
>> lack of documentation and examples for some really useful 
>> artifacts is damaging. Sometimes all it takes is adding "///" 
>> to one unittest.
>>
>>
>> Thanks,
>>
>> Andrei
>
> This is slightly off-topic, but: I've been encouraging my 
> friends and colleagues to use Dlang over the last year and the 
> one pain point they constantly tell me about is that the 
> documentation website is "difficult to use" and "looks 
> intimidating".

The problem is you click on "Language Reference" and what you 
actually get is a "Language Specification".

For example you click on "Modules" and you get this...

=====================================================
Module:
     ModuleDeclaration DeclDefs
     DeclDefs

DeclDefs:
     DeclDef
     DeclDef DeclDefs

DeclDef:
     AttributeSpecifier
     Declaration
     Constructor
     Destructor
     Postblit
     Allocator
     Deallocator
     Invariant
     UnitTest
     AliasThis
     StaticConstructor
     StaticDestructor
     SharedStaticConstructor
     SharedStaticDestructor
     ConditionalDeclaration
     DebugSpecification
     VersionSpecification
     StaticAssert
     TemplateDeclaration
     TemplateMixinDeclaration
     TemplateMixin
     MixinDeclaration
     ;
===========================================================

Who is that a reference for? I mean what user needs that 
information in that format? Sure if your actually writing a D 
compiler yourself that is probably useful... but if your a user?