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

[Moshe Zadka]

On Mon, 7 Feb 2000, Ka-Ping Yee wrote:

<me and Ping agree "guessing" is a bit dangerous>
> 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?

Assumption 1:
	doc-strings should be flexible enough to document most Python
	modules without any OOL documentation (that is, as I understand,
	our majority vote). The "most" comes because it shouldn't
	necessarily be flexible enough to write the reference manual for
	the debugger.

Assumption 2:
	the documentation must be convertible to XML, so various tools
	could use the XML to generate output formats in pleasent ways.
	(HTML, PDF, Word2K via COM)

Assumption 3:
	it must be "easy" to write doc-strings.

Assumption 4:
	the "easy" part shouldn't hamper an interested documenter from
	doing sophisticated things

Assumption 5:
	the doc-strings rules must be clear. We do not want to recreate
	Perl in docstrings.

Can we decide to agree on these assumptions? If we agree on these, I'm
sure we can formulate a spec conforming to them, more or less. OTOH,
if we can't, no spec will solve the problem.
--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.