[Doc-SIG] proposal: a process for solving the Python Documentation Problem

[Chad Whitacre]

Laura,

Thanks for giving me an opportunity to clarify my proposal.

I more or less agree with you that mixing "logical" and "rendering" 
information is "pure evil." However, the real world use case for this 
documentation is that it end up in several rendered formats. My 
suggestion is that explicitly identifying the most important rendered 
formats will help flush out the true requirements for the base (i.e., 
"logical" or semantic) format.

On the other hand, I confess that I don't follow your suggestion that 
separation of "logical" and "rendered" information leads to a plain text 
base format, one without any markup. Why exclude markup that is semantic 
rather than presentational?

Also, you hint that it might be helpful to define the problem itself 
more clearly, and I agree. The problem I want to see solved is 
Fredrik's: how do we cut the documentation workflow cycle down from 3-6 
months to, say, 3-6 days?




chad