Documentation Reorganization - June 2016
- Matt Zimmerman
- Former user (Deleted)
Owned by Matt Zimmerman
Currently targeting these changes for 1.2.4.
(see also: https://ccristudio.jira.com/browse/GEOMESASUP-934)
Specific Issues
| Issue/improvement | Notes | POC/Lead | Status |
|---|---|---|---|
| Retarget developer manual to contributing to GeoMesa itself | Follows example of other OS projects Current stuff in developer manual should be moved into user manual, probably cleaned up/consolidated | In PR | |
| Should user guide assume users are writing Java/Scala code? (Create separate system administrator guide?) | |||
| Clarify which parts of data management chapter are Accumulo-specific | |||
| Accumulo data store chapter | Can use text from developer manual | In PR | |
| Kafka data store chapter | Can use text from developer manual | In PR | |
| HBase/Google BigTable data store chapter | In PR | ||
| Cassandra data store chapter | In PR | ||
| Spark/Storm | Each has tutorials | ||
| Blob store | Described a little bit in command-line tools | In PR | |
| Native API | In PR | ||
| Stream data store | In PR | ||
| Stats | The stats command line tools are in that section | ||
| ETL and converter library | README.md has more information than Sphinx docs | In PR | |
| Aggregation operations (e.g. heat maps), WPS | Mentioned in tutorials. |
Things that need to be documented
- how to pass hints through geoserver viewparams parameter
- hints to select query strategy
- hints/system props to select cost strategy for selecting index
- hints/system props to select exact count behavior
- hints/system props to enable query timeouts
- system prop for number of ranges that will be split into multiple queries
- system prop for feature ID generation
- batch writer config - org.locationtech.geomesa.accumulo.GeomesaSystemProperties.BatchWriterProperties
- spark-sql, spark-sql rest API
- BIN formats? enabling gzip for BIN format
- Index improvements per specific versions, how updating versions will only use index improvements for new schemas e.g. why should users migrate data
- reserved keywords: GEOMESA-1229
- loose bbox config and implications
- query sampling
- sft keywords for geoserver layers
Proposed docs architecture (chapters and sections)
- Introduction
- Architecture Overview
- Installation and Configuration (comment: isn't this going to be mainly data store dependent-- mostly yes; created a section for each data store to avoid breaking the installation page too much)
- Accumulo Data Store
- Kafka Data Store
- HBase/BigTable Data Stores
- Cassandra Data Store
- Modules
- Blobstore
- Native API
- Stats API
- GeoServer
- Command-line Tools
- Data Management
- Examples
Sphinx docs vs. READMEs
In many cases there is confusion as to where the definitive documentation for a particular module should be; in the case of the converter library, for example, the README.md is more detailed than the relevant section in the Sphinx manual.
Possible solutions:
- Mirror READMEs to sections in the Sphinx docs (current solution)
- is error prone due to Markdown → RST conversion
- In effect have to maintain the same or similar text in two different places
- Replace READMEs with stubs that point to the relevant Sphinx docs?
- GitHub does render RST docs as text (e.g. https://github.com/locationtech/geomesa/blob/master/docs/user/installation_and_configuration.rst)
- but some formatting issues (i.e. substitutions will not be replaced, etc.)
- ???
/opt/devel/src/geomesa/geomesa-accumulo/geomesa-accumulo-datastore/src/main/scala/org/locationtech/geomesa/accumulo/accumulo.scala