deltaspike-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mark Struberg <strub...@yahoo.de>
Subject Re: [jira] [Created] (DELTASPIKE-13) Choose documentation format and tools
Date Fri, 23 Dec 2011 20:32:33 GMT
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
View raw message