Documentation Reorganization - June 2016

Currently targeting these changes for 1.2.4.

(see also:

Specific Issues

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 chapterCan use text from developer manual In PR
Kafka data store chapterCan use text from developer manual In PR
HBase/Google BigTable data store chapter  In PR
Cassandra data store chapter  In PR
Spark/StormEach has tutorials  
Blob storeDescribed a little bit in command-line tools In PR
Native API  In PR
Stream data store  In PR
StatsThe stats command line tools are in that section  
ETL and converter has more information than Sphinx docs In PR
Aggregation operations (e.g. heat maps), WPSMentioned 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 is more detailed than the relevant  section in the Sphinx manual.

Possible solutions: