Opened 2 hours ago
#846 new defect
Resolve documentation duplication between core and "getting started"
| Reported by: | Olly Betts | Owned by: | Olly Betts |
|---|---|---|---|
| Priority: | normal | Milestone: | 2.0.0 |
| Component: | Documentation | Version: | |
| Severity: | normal | Keywords: | |
| Cc: | Blocked By: | ||
| Blocking: | Operating System: | All |
Description
Some sections of the "getting started" guide are essentially the same as (or were substantially based on) documents in xapian-core/docs. In some cases the latter have since changed a bit too.
I don't think it's helpful to have to maintain two copies of these documents - better to just direct users to the "getting started" guide, which can be generated for each of the bindings target languages as well as C++, and where the formatting is nicer.
Some care is needed before removing from xapian-core to check if there are useful updates to merge across. I've made a start on this, but there's a bit more to do. It'd be good to sort out as much as possible before 2.0.0.
One thing I'm less sure about is the list of deprecated features - we definitely don't want to maintain this in two places either, but I wonder if this makes more sense to keep with the code as then the deprecation can get documented as part of the commit that changes the code, and it also means we automatically have versions for each release branch.
We could have separate 1.4.x and 2.0.x sections in the getting started guide, but then there's some duplication (e.g. environment variable XAPIAN_CJK_NGRAM was deprecated in 1.4.11 so will be removed in 3.0.0 so features in both). With versions of the document on both branches of the main repo a change to the entry for this on one branch gets considered for back-porting like a code change.
