[
https://issues.apache.org/jira/browse/NUTCH-881?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13113959#comment-13113959
]
Lewis John McGibbney commented on NUTCH-881:
--------------------------------------------
For the time being, I think it only appropriate to shelve the 2.0 documentation.
With regards to 1.X documentation what are be agreeing on here? Taking in to
consideration all of the above comments, I propose the following:
As the dev's agreed and moved documentation to SVN/site some time ago it
provides the following resources.
* About.html/pdf
* bot.html/pdf
* credits.html/pdf
* FAQ.html/pdf - This now displays a direct link to the wiki. Which is easier
for maintenance purposes
* index.html/pdf
* issue-tracking.html/pdf
* link-map.html/pdf
* mailing-lists.html/pdf
* nightly.html/pdf
* tutorial.html/pdf - this also contains some text and directs reads to the
official Nutch tutorial
* version-control.html/pdf
* wiki.html/pdf - same as comments for tutorial.html/pdf
I would consider the above the 'core' documentation for getting up and running
with Nutch, however I'm not sure if we agree on whether the wiki is adequate
enough to store the documentation, and whether it is tidy enough as well as
being a rich enough resource for people to find and utilise the specific
information they require.
In my opinion, the wiki has been working pretty well recently, there have been
several 'on the fly' edits in recent weeks to accommodate a range of
improvements suggested by the community. It has been a long process to get it
looking and feeling like a better information resource for the community,
however there is still lots to do. In addition, if we look at our sister
projects e.g. Hadoop, Tika the community uses the wiki extensively.
Any thoughts here about potential improvements or other Nutch specific
documentation we need to add or need to update ASAP before we consider this
issue resolved. I am working on an up-to-date Nutch & Hadoop tutorial and will
hopefully have it completed for the end of the weekend.
> Good quality documentation for Nutch
> ------------------------------------
>
> Key: NUTCH-881
> URL: https://issues.apache.org/jira/browse/NUTCH-881
> Project: Nutch
> Issue Type: Improvement
> Components: documentation
> Affects Versions: 2.0
> Reporter: Andrzej Bialecki
> Assignee: Lewis John McGibbney
>
> This is, and has been, a long standing request from Nutch users. This becomes
> an acute need as we redesign Nutch 2.0, because the collective knowledge and
> the Wiki will no longer be useful without massive amount of editing.
> IMHO the reference documentation should be in SVN, and not on the Wiki - the
> Wiki is good for casual information and recipes but I think it's too messy
> and not reliable enough as a reference.
> I propose to start with the following:
> 1. let's decide on the format of the docs. Each format has its own pros and
> cons:
> * HTML: easy to work with, but formatting may be messy unless we edit it by
> hand, at which point it's no longer so easy... Good toolchains to convert to
> other formats, but limited expressiveness of larger structures (e.g. book,
> chapters, TOC, multi-column layouts, etc).
> * Docbook: learning curve is higher, but not insurmountable... Naturally
> yields very good structure. Figures/diagrams may be problematic - different
> renderers (html, pdf) like to treat the scaling and placing somewhat
> differently.
> * Wiki-style (Confluence or TWiki): easy to use, but limited control over
> larger structures. Maven Doxia can format cwiki, twiki, and a host of other
> formats to e.g. html and pdf.
> * other?
> 2. start documenting the main tools and the main APIs (e.g. the plugins and
> all the extension points). We can of course reuse material from the Wiki and
> from various presentations (e.g. the ApacheCon slides).
--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
