Improving ddoc

[ketmar via Digitalmars-d]

On Thu, 01 Jan 2015 01:07:37 -0800
Walter Bright via Digitalmars-d <digitalmars-d at 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: not available
URL: <http://lists.puremagic.com/pipermail/digitalmars-d/attachments/20150101/4c38e7fc/attachment.sig>