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:40:17 GMT
+1

regards,
gerhard



2011/12/23 Mark Struberg <struberg@yahoo.de>

> Dan, I also like the results Andrew and Aslak had with that for the new
> Arquillian page.
>
> Could you probably provide a skeleton and sample integration which we can
> tweak?
>
> Best would be if you just create a git-clone and provide that on github.
> then we play around with it and if it turns out to be good, then we can
> just push this branch to ds.asf:master
>
> wdyt?
>
> LieGrue,
> strub
>
>
> ----- Original Message -----
> > From: Gerhard Petracek <gerhard.petracek@gmail.com>
> > To: deltaspike-dev@incubator.apache.org
> > Cc:
> > Sent: Friday, December 23, 2011 9:20 PM
> > Subject: Re: [jira] [Created] (DELTASPIKE-13) Choose documentation
> format and tools
> >
> > 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