deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gerhard Petracek <>
Subject Re: [jira] [Created] (DELTASPIKE-13) Choose documentation format and tools
Date Fri, 23 Dec 2011 20:20:43 GMT
hi dan,

i said: >if< there are too many open questions right now,...

we already discussed that we would use as few docbook-tags as possible (in
any case).
however, we are going to commit features quite soon and i would prefer to
have at least the basic descriptions in the repository from the very
beginning (instead of just waiting until this topic is resolved).


2011/12/23 Dan Allen <>

> On Fri, Dec 23, 2011 at 13:18, Gerhard Petracek
> <>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]
> [2]
> --
> Dan Allen
> Principal Software Engineer, Red Hat | Author of Seam in Action
> Registered Linux User #231597

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message