My experiences

The online documentation, a lot of which is installed with the compiler, is very readable. I’m a bit odd, but I found the documentation to be enjoyable reading. (I find Microsoft help to be useless and Microsoft online documentation to be needlessly obfuscated. (Unix’s man help pages are alright. They are uniformly terse, but are still complete and tend to actually answer the questions I have .) After I started working with the D compiler, I found that Digital Mars D Documentation suffers from two inexcusable lacks. First, there is no comprehensive index or table of contents. All month, I’ve been struggling with 2-3 recurrent problems with features which I want to use, but don’t remember how they worked. I’ve been searching the documentation for “const” and “function parameters" numerous times, but since Digital Mars uses Google as their index front end, the results are all original discussions of the feature in the forum archives (filled with people much smarter than I am) and buried somewhere is the actual documentation page. Continually searching for “site:digitalmars.com –archive class object” improves the results.

Request #1: The D Programming Language Documentation needs to be comprehensively indexed – both by subject and by concordance keyword.

The second lack in the documentation is its terseness. (This may be aggravated by the difficulty I found in finding answers). The documentation seems to be written by extremely smart people to explain to other extremely smart people the differences between C++ and D. (Or written to explain to a writer of another D compiler exactly how to implement it.) I would prefer that some things that should be obvious or are explained under another topic be spelled out in their own page. Something more on the lines of Programming in Lua by those guys, or The C++ Programming Language by Stroustrup. There are answers to many questions in the documentation, but you must randomly search for it. Only a little of the documentation appears to be available from the D Programming Language home page.

Request #2: The documentation needs to be doubled: preferably by explaining more things, but perhaps by merely storing related topics on separate pages with footer linking.

Remember, I said I found the documentation to be an enjoyable read. Since D has built in support for code auto-documentation, the library documentation tended to be complete. It also had a comprehensive table of contents as a sidebar. Again, repeatedly listing requirements and error cases would be nice for each function, instead of writing the doc once per module, but again this is a language written by very smart people for very smart people.

Beginning work: Dir2