www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Better D Documentation

reply Markus Dangl <danglm in.tum.de> writes:
Hi there,

IMHO the D documentation (digitalmars.com/d/) could be better. Because i 
like the way the PHP documentation (php.net/documentation/) is made, i 
decided to write a bit of PHP again... But before i get started, i want 
to collect ideas and thoughts about what could be improved by a new 
documentation system.

My thoughts:

1. The current doc isn't structured in an efficent way. When i am 
looking for unittests, i wouldnt look for it in the "classes" page. I 
plan to make a chapter for the language structure (explaining all the 
keywords...) and one for the libraries (only phobos atm).

2. The current doc is lacking a search function.

3. Comments on the doc pages (like php.net has) would be nice

4. A chapter on compiler errors would be really nice - these error 
messages can be quite puzzling and this would be a quick way to help 
other users understand what they did wrong.

Maybe we'll be able to generate the library doc from the sourcecode some 
time (ddoc is still "planning"), maybe we can even generate downloadable 
chm files. (I just don't know anything about chm at all - but the PHP 
ones are useful *g*)

Any suggestions?

- Markus Dangl

P.S.: If anyone is actually working on a similar project i'd gladly 
offer my assistance...
Dec 28 2004
next sibling parent reply "Jarrett Billingsley" <kb3ctd2 yahoo.com> writes:
I'd definitely like to see this (and in fact, just yesterday, I was just
about ready to dump the docs all into a CHM so I could easily search them..
but now you're doing it, and will probably do a better job than anything I'd
make ;) ).

I think some more thorough Phobos documentation with examples would be
great.
Dec 29 2004
next sibling parent Markus Dangl <danglm in.tum.de> writes:
Jarrett Billingsley schrieb:

 I'd definitely like to see this (and in fact, just yesterday, I was just
 about ready to dump the docs all into a CHM so I could easily search them..
 but now you're doing it, and will probably do a better job than anything I'd
 make ;) ).
 
 I think some more thorough Phobos documentation with examples would be
 great.
 
 


Great to hear some response! My motivation just jumped to 100% :)

I hope no one working on the current documentation feels offended when 
i'm criticising. I'll just do a user-editable (almost wiki-like?), 
searchable doc-Website in PHP, then we got to add some content. I dont 
think we can just copy-n-paste the original doce (see the "all rights 
reserved" at the bottom?), so i'll try to write a bit myself. My english 
isn't perfect, but i think my mistakes will get fixed fast enough once 
the site is reviewed by other users!

Thanks,
Markus
Dec 29 2004
prev sibling parent "Asaf Karagila" <kas1 netvision.net.il> writes:
"Jarrett Billingsley" <kb3ctd2 yahoo.com> wrote in message 
news:cqujqa$10me$1 digitaldaemon.com...

 I'd definitely like to see this (and in fact, just yesterday, I was just
 about ready to dump the docs all into a CHM so I could easily search 
 them..
 but now you're doing it, and will probably do a better job than anything 
 I'd
 make ;) ).

 I think some more thorough Phobos documentation with examples would be
 great.


another pretty annoying thing is the "works just like in C"
but what if i am not as good with C ? what if i don't know how to declare 
structs in C,
simply because i never worked with it before..
a bit more explaining is needed in my opinion..

- Asaf.
Dec 30 2004
prev sibling next sibling parent Bastiaan Veelo <Bastiaan.N.Veelo ntnu.no> writes:
Markus Dangl wrote:

 Maybe we'll be able to generate the library doc from the sourcecode some 
 time (ddoc is still "planning"), maybe we can even generate downloadable 
 chm files. (I just don't know anything about chm at all - but the PHP 
 ones are useful *g*)
 
 Any suggestions?


Ant has a working alternative to doxygen (and ddoc). See the thread 
"Document generator" started at dec. 4.


Bastiaan.
Dec 29 2004
prev sibling next sibling parent reply "Lynn Allan" <l_d_allan adelphia.net> writes:
Something to be aware of (if not already)

D documentation has an associated set of d-wiki pages. (May actually
be several?) One purpose is to let people make suggestions to the
documentation author (generally The WB).

Perhaps this approach could be built on so that the documentation is
more open to (registered?) d-wiki authors.
(d-wiki link is ???? .... D website seems to be down??)

One of the problems with the existing web based documentation is that
the "Search" button doesn't facilitate constrained searches.

For example, to search for "mixins" and restrict to the archives:
mixins +archives

To look in the docs (without the archives)
mixins -archives -wwwnews -wwwpost
Dec 30 2004
parent "Lynn Allan" <l_d_allan adelphia.net> writes:
 (d-wiki link is ???? .... D website seems to be down??)


http://www.prowiki.org/wiki4d/wiki.cgi
Dec 31 2004
prev sibling next sibling parent Gold Dragon <dragonwing dragonu.net> writes:
Markus Dangl wrote:

 Hi there,
 
 IMHO the D documentation (digitalmars.com/d/) could be better. Because i 
 like the way the PHP documentation (php.net/documentation/) is made, i 
 decided to write a bit of PHP again... But before i get started, i want 
 to collect ideas and thoughts about what could be improved by a new 
 documentation system.
 
 My thoughts:
 
 1. The current doc isn't structured in an efficent way. When i am 
 looking for unittests, i wouldnt look for it in the "classes" page. I 
 plan to make a chapter for the language structure (explaining all the 
 keywords...) and one for the libraries (only phobos atm).
 
 2. The current doc is lacking a search function.
 
 3. Comments on the doc pages (like php.net has) would be nice
 
 4. A chapter on compiler errors would be really nice - these error 
 messages can be quite puzzling and this would be a quick way to help 
 other users understand what they did wrong.
 
 Maybe we'll be able to generate the library doc from the sourcecode some 
 time (ddoc is still "planning"), maybe we can even generate downloadable 
 chm files. (I just don't know anything about chm at all - but the PHP 
 ones are useful *g*)
 
 Any suggestions?
 
 - Markus Dangl
 
 P.S.: If anyone is actually working on a similar project i'd gladly 
 offer my assistance...



Well, if you need help with the project I would provide assistance with PHP
coding, database table 
design, and I would like to write some of the documentation myself but yeah, I
think some of the 
more veteran D coders should write the more advance parts.

There are some PDF files that basically copied and paste the pages on the web
site and just 
organized them better (or something, it has been a while since I checked).
Dec 31 2004
prev sibling parent reply J C Calvarese <jcc7 cox.net> writes:
Markus Dangl wrote:

 Hi there,
 
 IMHO the D documentation (digitalmars.com/d/) could be better. Because i 
 like the way the PHP documentation (php.net/documentation/) is made, i 
 decided to write a bit of PHP again... But before i get started, i want 
 to collect ideas and thoughts about what could be improved by a new 
 documentation system.
 
 My thoughts:
 
 1. The current doc isn't structured in an efficent way. When i am 
 looking for unittests, i wouldnt look for it in the "classes" page. I 
 plan to make a chapter for the language structure (explaining all the 
 keywords...) and one for the libraries (only phobos atm).


I agree some reorganization could be helpful.


 
 2. The current doc is lacking a search function.


Have you tried http://www.digitalmars.com/advancedsearch.html?

(It's not perfect, but it's better than nothing.)

Also, you could download a PDF snapshot 
(http://www.prowiki.org/wiki4d/wiki.cgi?LanguageSpecification) and 
search that file.


 
 3. Comments on the doc pages (like php.net has) would be nice


Have you seen http://www.prowiki.org/wiki4d/wiki.cgi?DocComments yet? 
Many people have already added comments. Each page of the spec already 
links to a corresponding wiki page ("feedback and comments").


 
 4. A chapter on compiler errors would be really nice - these error 
 messages can be quite puzzling and this would be a quick way to help 
 other users understand what they did wrong.


Here's a start...
http://www.prowiki.org/wiki4d/wiki.cgi?ErrorMessages


 
 Maybe we'll be able to generate the library doc from the sourcecode some 
 time (ddoc is still "planning"), maybe we can even generate downloadable 
 chm files. (I just don't know anything about chm at all - but the PHP 
 ones are useful *g*)
 
 Any suggestions?
 
 - Markus Dangl
 
 P.S.: If anyone is actually working on a similar project i'd gladly 
 offer my assistance...


Everyone is welcome to help edit and add to the wiki pages.

-- 
Justin (a/k/a jcc7)
http://jcc_7.tripod.com/d/
Jan 02 2005
parent Markus Dangl <danglm in.tum.de> writes:
 Have you tried http://www.digitalmars.com/advancedsearch.html?
 
 (It's not perfect, but it's better than nothing.)


Oh, didn't see that (i could've remembered the google function for 
searching a specific page).


 Also, you could download a PDF snapshot 
 (http://www.prowiki.org/wiki4d/wiki.cgi?LanguageSpecification) and 
 search that file.


Hm but an online (web) manual may even auto-generate PDF for us :)


 Have you seen http://www.prowiki.org/wiki4d/wiki.cgi?DocComments yet? 
 Many people have already added comments. Each page of the spec already 
 links to a corresponding wiki page ("feedback and comments").
 (...)
 Here's a start...
 http://www.prowiki.org/wiki4d/wiki.cgi?ErrorMessages
 


These two links are very helpful. Of course they could be a bit easier 
to use (esp. the first one...)


 P.S.: If anyone is actually working on a similar project i'd gladly 
 offer my assistance...


 
 
 Everyone is welcome to help edit and add to the wiki pages.
 


I thought about joining the wiki project, but i disliked the looks of 
the current wiki - it's kind of problematic to have 2 seperate places 
for documentation, too. Actually i'm working on a wiki-style 
documentation system which will be tailored to documenting D :)
Let's see what i can do and if it's really better than the current system.
Jan 02 2005