Consolidate documentation

[rolyp]

There is a lot of overlapping documentation for TGVE, with many similar (but not identical) fragments of text. For example, there is significant redundancy between:

• README.[R]md for the various repos
• tgve/eAtlas/notes/guide.Rmd
• tgve/eAtlas/wiki (generated from eAtlas/notes/guide.Rmd and pasted into wiki by hand)
• tgve/tgver/vignettes (e.g. tgver.Rmd)

Reorganise to achieve the following:

• no topic is documented more than once
• when information needs to be included in multiple places, using linking/sharing, instead of copying

Meta-tasks:

• list of main topics that need documentation? (see below as a starter)
• remove promissory notes
• remove "As of version 1.3.5-beta.0..." remarks
• decide where to put each topic -- e.g. against particular repo, or wiki page
• delete any remaining README.Rmd files (return to automation later if need be)

Initial pass over:

• home
  • introduction
  • showcases (rename to "example applications")
  • roadmap (delete bullet about configuration settings)
  • contributing
  • package status
  • funding
• development setup
  • testing
  • GitHub template repo (was: using GitHub Pages)
• (R package) tvge/tgver/README.md
• (Node.js package) tvge/eAtlas/README.md
  • API parameters
  • separate geography source (integrated into discussion about API parameters)
• (app template) tgve/app/README.md
  • technical notes
• (full stack app template) tgve/full-app.README.md
  • using in a Python Flask app
  • technical notes
• using the deployed instance
• using your own local instance
  • Docker image
  • Other method (needs revisiting)
• delete:
  • references (use hyperlinks instead)
  • reproducible TGVE (best left in notes/reproducible.Rmd)
  • outside the browser/native desktop app (best left in notes/native.Rmd)

Pass over each of:

• tgve/eAtlas/wiki
• tgve/eAtlas/notes/guide.Rmd (delete)
• tgve/spenser/README.Rmd (see tgve/spenser#1)
• tgve/tgver

Additionally:

• pass over everything to check for broken links, etc -- fold this into other ongoing issues
• is Wiki really justified now? no, move remaining Wiki pages to eAtlas

[layik]

Fantastic work @rolyp. Got my roadmap for docs.

[rolyp]

Summary of the docs that need revisiting and topics they cover:

• tgve/eAtlas/README.md
  • API variables
  • using GitHub Pages
  • development setup
  • testing
• tgve/eAtlas/notes/guide.Rmd
  • introduction
  • API variables
  • using GitHub Pages
  • Docker
  • using R package
  • npm package
  • outside the browser
  • showcases
  • roadmap
  • references
• tgve/eAtlas/wiki
  • introduction
  • npm package
  • GitHub template repo
  • development setup
  • using R package
  • Docker
  • funding
• tgve/eAtlas/wiki/Developing-eAtlas
• tgve/eAtlas/wiki/Reproducible-TGVE
• tgve/eAtlas/wiki/Using-TGVE
  • introduction
  • deployed instance
  • API variables
  • using GitHub Pages
  • Docker
  • using R package
  • using Flask
  • npm package
  • outside the browser
  • showcases
  • roadmap
  • references
• tgve/eAtlas/wiki/Using-TGVE-as-Native-App
  • native desktop app
• tgve/eAtlas/wiki/Using-TGVE-in-Flask-(Python)
  • what is Flask
  • GitHub template repo (from Flask)
  • serving data to TGVE
• tgve/eAtlas/wiki/Using-TGVE-Locally
• tgve/app/README.md
  • usage
  • separate geography source
  • development setup
  • notes
• tgve/full-app
  • usage (Flask, plumber, nodeJS)
  • technical
• tgve/spenser/README.Rmd (see tgve/spenser#1)
• tgve/tgver
  • introduction
  • tgver
  • development plan
  • funding
  • contribution
  • package status

[layik]

@rolyp great work. Can we possible leave current repo README with contents of whatever it points to saving users a click? It is also published as the landing page on npmjs.com. As the application grows we can point users to a doc Wiki or in future a doc portal. It will also be consistent with other repos of the organisation.

[rolyp]

@layik Yes, I'm wondering how best to achieve something like that (without reintroducing the lots of copy and paste). I'll have a think about that today, and implement the same solution for each repo.

[rolyp]

@layik Completed an initial pass with the main goals of:

• removing redundancy (document each thing in one place)
• merging fragments of related documentation into appropriate location (e.g. tgver for R-related stuff)

For example, most of guide.md was redundant with what was written elsewhere, but when not, I've merged the relevant content. The Wiki has gone for the same reason (since it was just a manual copy-and-paste of guide.md).

That is not to the say that documentation we're left with is accurate/complete. We will need to make a careful pass over the docs as we move forward but I suggest we do that as part of the other ongoing build/deployment issues.

Final note: if we want to duplicate certain essential bits of text into every repo (e.g. Code of Conduct, Funding, overview of project, etc) we can look at some way of doing that without relying on copy/paste. For this specific task, my goal has been to get to a sane (=single, unique) version of the docs so that we can move forward from there.