Our docs should be more beautiful

Charles Hixson via Digitalmars-d digitalmars-d at puremagic.com
Thu Jul 21 11:33:03 PDT 2016


I think the Python docs looks better and are more useful...but the older 
Python docs were even better.  Sometimes fancier HTML just makes things 
less useful.

That said, I think that when feasible docs should be auto-generated from 
code included within the code files.  More like ddoc or javadoc then 
Sphinx or such.  But this shouldn't necessarily apply to the basic 
frameworks.  The basic D documentation is extremely good, it's when we 
get to the libraries that things become a bit iffy.  (Then again, I 
don't like the template syntax.  I thought the D1 docs were better than 
the D2 docs, but this might be because when they were rewritten they 
assumed things that give me trouble.  I prefer the way that Python 
handles ranges to the way the D does. Etc.  These impact the 
understanding of the documentation of many Phobos files.)


On 07/18/2016 06:41 PM, Andrei Alexandrescu via Digitalmars-d wrote:
> On 07/18/2016 09:28 PM, Carl Vogel wrote:
>> Racket's docs have actually been designed by a professional typographer,
>> so might be a good reference point. Example:
>> https://docs.racket-lang.org/reference/flonums.html
>
> They do look nice! -- Andrei
>



More information about the Digitalmars-d mailing list