On Tue, Oct 30, 2012 at 08:50:50PM +0100, Jacob Carlborg wrote: > On 2012-10-30 17:09, Tobias Pankrath wrote: > > >I agree, that the online docs are insufficient for learning the > >language. But that's the case for phobos, too. Both are just a > >listings of what is there and don't give you any overview of what > >design decisions were made and what implications they have. > > > >Just take a look std.container. > > > >I hope that Ali Çehreli efforts will be midterm solution at > >least for the language docs. Maybe he should credits by linking > >from the homepage to his book. > > A language needs several types of documentation. Reference > documentation (basically what we have now), higher level > documentation, tutorials and examples. [...]
I contend that much of the current documentation isn't even up to reference standard. Incompleteness, for one thing. Things like Throwable and Exception aren't even documented right now (though this has been fixed in git HEAD). I'm sure there are many other fundamental holes. And a randomly-sorted list of unrelated module items does not constitute a reference, either. It has to be at least sorted alphabetically, or preferably, by logical categories. And things like class members need to be properly indented (I think this was fixed recently) instead of being flattened out, making it impossible to discern whether it belongs to the previous declaration or the global module scope. Moreover, nested classes/structs, etc., need to be put AFTER simpler members. It's basically unreadable when, for example, two int members are separated by the docs of a 2-page nested struct. And don't even get me started on navigability. Dumping a morass of #-links at the top of the page does not a navigable page make. Some modules NEED to have docs split into separate pages. A 10-page infodump of randomly sorted items is simply impossible to use effectively. Clickable identifiers would be nice, so that you don't have to separately navigate and lookup a particular symbol when you're not sure what it means, while trying to keep track of where you left off (and I thought we were in the age of automation...). T -- The right half of the brain controls the left half of the body. This means that only left-handed people are in their right mind. -- Manoj Srivastava
