Re: Fwd: Help document Plone's API
Martin Aspeli <[email protected]>
| Newsgroups | gmane.comp.web.zope.plone.documentation |
|---|---|
| Message-ID | <[email protected]> |
Mikko Ohtamaa wrote: > Also, Sphinx seems to be the upcoming de facto standard to document > Python. I hope we don't have yet another case here of being > unpythonic. This misses the point. "Pythonic" is a word we use to talk about coding conventions. Applying it to documentation is silly. We have a proven, feature rich content managed solution on plone.org that has existed much longer than Sphinx has. It has a review cycle. It is accessible to people like JoAnna and Veda that I'm sure will not be happy to manage our documentation via an svn client and an obscure plain text markup. I'm not interested in a debate to displace that. I'm even less interested in fracturing our documentation into multiple sources that can't be easily cross-referenced, searched or integrated in terms of navigation and structure. Rather than this vaguely posturing that some different technology may be better for producing the content, we should focus on the important part: the content itself. For better or worse, PHC is the documentation story on plone.org, and there is no clear path or consensus for using anything else. In the worst case, we'll end up with a half-arsed solution that no-one maintains, no-one knows where to access, and no-one knows how to integrate into plone.org. In the best case, we spend a ton of effort on technology that we could spend on content and still be no better off. The document I'm talking about here will contain a lot of very small pages, each with maybe 2-10 lines of code pasted in. I'm not having a very hard time doing that with kupu at the moment for the Dexterity manual, so I'm sure we'll manage for this. :) Martin -- Author of `Professional Plone Development`, a book for developers who want to work with Plone. See http://martinaspeli.net/plone-book ------------------------------------------------------------------------------ Register Now for Creativity and Technology (CaT), June 3rd, NYC. CaT is a gathering of tech-side developers & brand creativity professionals. Meet the minds behind Google Creative Lab, Visual Complexity, Processing, & iPhoneDevCamp as they present alongside digital heavyweights like Barbarian Group, R/GA, & Big Spaceship. http://p.sf.net/sfu/creativitycat-com