On Fri, Dec 23, 2011 at 13:18, Gerhard Petracek <[email protected]>wrote:
> if there are too many open questions right now, i would suggest that we > start with docbook and evaluate the alternatives within the next weeks. > Choosing docbook for this reason seems like just giving up before the match begins. Jason is absolutely right that docbook is a huge barrier to open source contributions and totally overkill/bloatware for writing sentences. Sphinx allows you to do just that, write sentences. No B.S. No special editor. No angled brackets. Just type. It's essentially markdown, or a variant of it [1], put into a scaffolding for a book. The Maven plugin seems very up to date and I really doubt there will be much trouble to get it to run [2]. With Sphinx, you are going to get better docs from day one. Any project should jump at that prospect, given how notorious projects are for having bad docs. "Sphinx is a tool that makes it easy to create intelligent and beautiful documentation" Btw, we aren't necessarily advocating for Sphinx as we are advocating for writing docs in plain text. Sphinx just happens to offer the best scaffolding for that purpose. And proven. -Dan [1] http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#quick-syntax-overview [2] https://github.com/tomdz/sphinx-maven/blob/master/README.md -- Dan Allen Principal Software Engineer, Red Hat | Author of Seam in Action Registered Linux User #231597 http://www.google.com/profiles/dan.j.allen#about http://mojavelinux.com http://mojavelinux.com/seaminaction
