On May 29, 2008, at 8:31 AM, Ittay Dror wrote:
Did you guys think of structuring the documentation section like
vim.sf.net
or mysql's site? In both of them, users can add comments to the
documentation page. These comments usually have a wealth of
information in
them.
Related to that, why the separation of wiki and documents? A wiki
with the
documents and with an ability for adding comments at the buttom,
will be
excellent.
I definitely see the positive side of such an approach. Yet there are
a couple of reasons why we don't do this.
- I like to have a PDF version of the documentation (e.g. for nice
searching). We are hosted at codehaus which provides us the
confluence wiki. Confluence does not preserve the order when
exporting to PDF. The chapters in your PDF are always alphabetically
sorted. The confluence guys are working on this, but I don't know
when this is released and when codehaus updates to this new version
of confluence.
- I don't know about the other wikis. What I think is essential for a
robust documentation is automatic generation of chapter, section and
subsection numbers. Also the possibility to create links to labels,
so that you don't have to worry about fixing the references when you
add sections to it. Sooner or later we will also create and index for
our documentation.
- The layout of Latex is very nice.
- Most of the code snippets in the documentation are integration
tests. We automatically include the source code of the tests into the
documentation. When we execute the tests we capture the output and
include this output also in the documentation. I wouldn't know now to
do this with confluence.
One possible way of combining both approaches would be to export the
generated documentation into a wiki.
- Hans
Ittay
--
View this message in context: http://www.nabble.com/site-suggestion-
tp17528465p17528465.html
Sent from the gradle-dev mailing list archive at Nabble.com.
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
--
Hans Dockter
Gradle Project lead
http://www.gradle.org
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
