Re: Fwd: Fwd: Help document Plone's API
Clayton Parker <clayton-qEDqLqPM/[email protected]>
| Newsgroups | gmane.comp.web.zope.plone.documentation |
|---|---|
| Message-ID | <[email protected]> |
On May 27, 2009, at 7:34 AM, Mikko Ohtamaa wrote: > <snip> > >> 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. > > Developer manual writers are Python developers. Developer manual > readers are Python developers. They are quite familiar with tools like > SVN and Sphinx. The problem is the integration part. > > "Developers hate to write documentation in Kupu": > http://n2.nabble.com/Re%3A-If-core-code-is-undocumented-it%27s-broken-%28Was%3A-where-should-developer-documentation-go-%29-tp1511898p1565179.html You don't *have* to use Kupu. I personally do not care for WYSIWYG editors at all. They usually hinder my writing by forcing me to figure out how to create the markup that I already know how to create. I am a huge proponent of Markdown (http://daringfireball.net/projects/markdown/basics ), I think JoAnna is even coming around to liking it a little bit :) It has a very simple syntax and writing code blocks is dead simple, just indent four spaces, I love that! I would rather promote creole since it aims to standardize plain text markup, but it has not gained much traction yet :( That being said, it's not the magic solution to solve everything, it has it's issues as well. But I think this could serve as a nice medium for developers and non-developers. claytron -- S i x F e e t U p , I n c . | http://www.sixfeetup.com Phone: +1 (317) 861-5948 x603 clayton-qEDqLqPM/[email protected] ANNOUNCING the first Plone Immersive Training Experience | Sept. 10-11-12, 2009 http://www.sixfeetup.com/immerse ------------------------------------------------------------------------------ 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