deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gerhard Petracek <gerhard.petra...@gmail.com>
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).

regards,
gerhard



2011/12/23 Dan Allen <dan.j.allen@gmail.com>

> On Fri, Dec 23, 2011 at 13:18, Gerhard Petracek
> <gerhard.petracek@gmail.com>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
>

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