[Doc-SIG] Re: Ease of use is #1

Ka-Ping Yee ping@lfw.org
Mon, 7 Feb 2000 03:09:32 -0800 (PST)

On Mon, 7 Feb 2000, Moshe Zadka wrote:
> No, 10 lines of description and 450 lines of a module done up in the way I
> propose.

I apologize.  I did read your message, but clearly 450 was an unfair
exaggeration.  I should have simply stated that the description was
longer and more involved that i would have preferred.

> While I admire the way you markup by "guessing", I must admit I have my
> qualms about this approach: too little control for the documenter.

I entirely agree with you that the markup rules cannot be complicated
and mysterious.  In fact, i cringe at the word "guessing" in much the
same way you probably do.  It is crucial that the rules be simple and
their behaviour easily understood.

Let's work together to whittle the problem down to its essentials, then.
In your opinion, what kinds of things must the documenter be able to
precisely control?  Could you prioritize a list?

-- ?!ng