I've been dodging this thread because I don't really have much to add, apart from a documentation end user point of view...
On Fri, 2005-12-30 at 09:25 +0100, Fredrik Lundh wrote: [...] > > Another goal is highly biased toward XML-style markup: > > > > * Make it trivial to do basic rendering to HTML (a few re.sub > > calls should suffice), to enable simple tools (CGI scripts, etc) > > to be able to render reference documentation. > > > > This is the tail wagging the dog. > > No, it's a fundamental goal: to support light-weight generation of rendered > markup directly from source code, to enable simple tools (CGI scripts, etc) > to be able to render reference documentation. Python is run-time interpreted, but I don't think we need its documentation to be. "trivial" is a relative term. From my point of view, provided I can apt-get one or to not-too-esoteric packages then do something like "make html", it's trivial enough for me. > The issue this is addressing is that the current workflow is way too heavy; > when I made my first post, it typically took 3-6 months for a contribution to > the documentation to appear on python.org. Thanks to Trent and Neal, the > situation is a bit better today, but it's far from ideal. (More on this > below). [...] > That's why I'm listening to people who've tried to use ReST for this pur- > pose. They've all failed. Maybe they also only understood ReST super- > ficially. Or maybe it's because ReST is created by people who have a > very shallow understanding of the issues involved in writing structured > reference documentation. Your guess is as good as mine. As a some-times developer not really interested in writing documentation, I must admit I really like ReST. It looks like plain text, so I can write and use it as plain text, but it also can magically transform to other formats and look pretty good. I hate writing XML/HTML, and my only experience with LaTex was brief and painful too. If I was forced to choose, I'd probably pick LaTex even though I don't know it as well as XML/HTML (I'd rather face an unknown evil than that particular devil I know). > > My bias is simple: I am against wasting the time and effort required > > to replace one form of verbose markup with a different but equivalent > > form. The proposed solution is no better than the status quo. > > Support for quick turnaround, edit via the web, richer semantic information, > and a larger existing toolbase isn't better than the status quo ? [...] I'm not going to write docs for stuff I didn't write myself. I'm not going to submit patches to Javadoc, LaTex or XML/HTML, but I might post vague "change this to..." bug reports. As an end user, one of the best things about Python is the on-line documentation... the status-quo looks pretty good from here. ...but I'm not the person doing it... remember I'm providing a documentation end-user POV here :-) > > IMO, the markup itself is almost irrelevant. As others have stated, > > writing good documentation is hard. People will latch on to any > > excuse to avoid it, and markup is convenient. But even if the docs > > had no markup whatsoever, if they were written in plain text like > > RFCs, I doubt there would be significantly more patch contributions. Writing good documentation is hard (which is why I prefer to leave it to others if I can), but fixing almost good documentation doesn't have to be, and for that, the markup used can make a difference. As an end user that spots a problem, I'll look at the source, and if it's in a language I know well enough to fix the problem, I'll submit a patch. If I find it's in a language I don't know and can't grok well enough to see how to fix the problem in 10 minutes, I'm going to submit a verbal description as a bug. If this is the 5+ time I've stalled on this language, I might consider learning it so I can do a patch next time. However, in this case the language in question is a "documentation language" and I want to be a software programmer, not a document publisher, so I'll probably just submit bugs every time, and after the 2+ time I won't even bother looking at the source. > It's the workflow that's the real problem here, but you cannot fix the > workflow > without fixing the markup. I must say I disagree with this statement... changing the markup will not change the workflow at all, just shave 3-6 mins off the compile-test step. I don't do this enough to really know if that's worth it. If the markup is changed to something more widely known and/or simple, more people might participate in the "generate patch" workflow rather than the "submit bug" workflow, and maybe that will make things easier for the big picture "update and release docs" workflow. But the speed of the tool-chain has little to do with this, only the "documentation language" popularity among the developers and users. ...and if the LaTeX guys don't mind fixing bugs instead of applying patches and are handling the load... the status quo is fine by me, I'm happy not to do documentation :-) -- Donovan Baarda <[EMAIL PROTECTED]> http://minkirri.apana.org.au/~abo/ _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
