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...

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.

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.

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

"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.

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

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).

> (d-wiki link is ???? .... D website seems to be down??)

http://www.prowiki.org/wiki4d/wiki.cgi

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/

> 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.