On Thu, 01 Jan 2015 01:07:37 -0800 Walter Bright via Digitalmars-d <digitalmars-d@puremagic.com> wrote:
> And lastly, the general problem users have with documentation in Phobos is > not > that it is written in Ddoc. That has NOTHING to do with it, it's an excuse. > Nobody has yet taken me up on my offer to take their text documentation and > add > markup for them. Few people being willing to write good content is the > problem. > No documentation tool can fix that. Non-existent documentation can be not > written using any tool. Adam already told that people who can write good documentation is rarely need it. so they just DON'T HAVE that documentation written in the way it can be useful for others. so the only way to make such people write something is to make documentation formatting unintrusive. Ddoc IS intrusive. i can fix something if i can read it, and i can't read that Ddoc mess. so i'm going to dlang.org to look at the dox instead of looking it right in the Phobos sources. and if i see something that can/should be fixed on dlang.org... ah, well, i have to drop the thing i was doing, open another terminal, go to Phobos source directory, find the file with the dox, then find the place to fix... screw it, i was looking at documentation for doing completely different things! but see, if Phobos documentation is human-readable without preprocessing, it's WAY EASIER for me to just open Phobos source file and look there. and guess what i'll do if i'll see that something needs fixing there? yep, i'll fix that, 'cause i'm already at the place that needs fixing. the process is not distractive. and then i can do 'git diff' and send a patch. the whole point is that Ddoc is *not* *human* *readable*. so why i should look to Phobos sources and try to decipher it? and i don't want to drop whatever i was doing to go from the site to Phobos. and when i done with my task, i already forgot what requires fixing (or exhausted and don't want to do it). i understand that D is your child, and you are working on it with passion. but for me D is the tool to solve my tasks. i'm ready to help improving that tool, but only if that's as easy as possible for me. when i done with my task, i already know what i wanted to know, so there is little sense in fixing that. i'm done with it, now i remember it. or at least remember in which of my source files i should look when i need to refresh my memory (yep, i'm looking for usage samples and patterns in my sources if i can, 'cause it's way easier to open another source file for me than to go to some webpage, even local one). that's why i'm advocating human-readable markup. it's easier to read. it's easier to write. it's easier to fix. it can be used without preprocessor. any decent IDE (and even my patched mcedit) can open source file with function definition in one or two clicks. i can't fix it inplace -- i will not fix it. i can't do 'git diff' with it -- i will not fix it. i can't read it -- i will not fix it. and all this is solvable, even without sacrificing your beloved Ddoc: we can have BOTH markdown-like and Ddoc simultaneously. do that and see what language people will prefer to use.
signature.asc
Description: PGP signature