[
https://issues.apache.org/jira/browse/NUTCH-881?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Julien Nioche updated NUTCH-881:
--------------------------------
Fix Version/s: (was: 1.9)
1.10
> 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: nutchgora
> Reporter: Andrzej Bialecki
> Assignee: Lewis John McGibbney
> Fix For: 1.10
>
>
> 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 was sent by Atlassian JIRA
(v6.2#6252)
