I would say Markdown could be the way forward. Apache is currently in
process of phasing out Confluence and adopting a new CMS
(/http://www.apache.org/dev/cms.html/) for wiki documentation which is
based on Markdown. Adopting markdown would have the plus of having the
maven site and the other documentation in the same format.
regards
Rahul
On 12-07-2012 05:07, Patrick Hunt wrote:
I'd suggest something other than markdown, it's not rich enough, from
zk discussion (we went with textile in the end on top of CMS):
Ben Reed:
"after deciding to go with markdown and converting the
zooKeeperProgramming guide. i realize textile is the way to go. the
problem is that the table support in markdown is non-existent as is
the ability to create anchors for links in a document."
https://issues.apache.org/jira/browse/ZOOKEEPER-925
Patrick
On Wed, Jul 11, 2012 at 11:28 AM, Josh Wills <[email protected]> wrote:
I lean Markdown, primarily out of ignorance at this point. :) Does anyone
else have a strong opinion on this?
On Wed, Jul 11, 2012 at 11:22 AM, Matthias Friedrich <[email protected]> wrote:
Hi,
I set up the new Maven site using Markdown because we already had one
document in Markdown syntax. I think before we add more documentation
we should decide for a Doxia module [1] before it's too late :)
With Doxia we have the following alternatives:
XDoc is the old Maven 1 format that is still used by many Apache
projects. It uses XML which makes it a bit unpleasant to use,
especially for code examples.
APT is the main Maven 2 format. We use it extensively at work, but
it's the worst plain-text markup language I've ever used. You can get
used to it though and it works.
Markdown is pretty popular on Github. It has its weird corners and
the Doxia module seems pretty young. The error messages it generates
weren't very helpful to me and breadcrumbs are broken (do we need
them?).
Confluence/Textile has the advantage that you *might* be able to copy
and paste stuff from the wiki to the Maven site. I don't know how
well the module works.
So, which one do you want to use?
Regards,
Matthias
[1] http://maven.apache.org/doxia/modules/index.html
--
Director of Data Science
Cloudera <http://www.cloudera.com>
Twitter: @josh_wills <http://twitter.com/josh_wills>
