Opened 4 weeks ago
Last modified 11 hours ago
#846 new defect
Replace remaining written core docs with "getting started" or "developer guide" sections
| Reported by: | Olly Betts | Owned by: | Olly Betts |
|---|---|---|---|
| Priority: | normal | Milestone: | 2.x |
| 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.
Change History (2)
comment:1 by , 32 hours ago
| Milestone: | 2.0.0 → 2.0.x |
|---|---|
| Summary: | Resolve documentation duplication between core and "getting started" → Replace remaining written core docs with "getting started" or "developer guide" sections |
I've dealt with the low hanging fruit.
Some discussion in #xapian lead to the plan to aim to ultimately move or replace the xapian-core written docs with docs in the getting started guide or developer guide, and then move these to a new xapian-docs module in the git tree so I'm repurposing this ticket to track that.
(The doxygen-generated API docs would remain in xapian-core.)