konveyor/tackle-data-gravity-insights

Separate docs between user and developer

Closed this issue · 0 comments

There needs to be clear separation between ‘usage’ and ‘development’. We have that in the docs, but not quite.

Suggest the following changes:

  • There is ‘Usage’ section, and then ‘Contributing’ section.
  • ‘Getting Started’ doesn't belong in the contributing section, because it has no development activity in there - it is about running sample application. At a high level, there needs to be ‘Getting Started’ (which already has the usage part), and ‘Contributing’ which will have dev environment setup.
  • Docker setup should be moved to the Getting Started as a requirement because you need docker whether or not you are contributing (even for regular usage).
  • When we talk about running the sample application, there is an instruction to clone the repo and use the ‘demo’ directory in the repo. Cloning is un-necessary here. You can download day trader to any directory, build and still use c2g and s2g on it because you already have pip installed tackle-dgi per the user guide. We can take the cloning part out and change the references to demo directory to any local directory.
  • Following the Usage section and then the developer environment setup, there is a conflict with the neo4j container name. You have to remove the container that was created before with the same name. Need to fix the docs.
  • It seems that wget and mvn need to be mentioned as requirements in the getting started guide or eliminated by using a Docker container that doesn't require them. MacOS doesn't come with wget by default (neither does Windows).
  • Typo - ‘gdi’ instead of ‘dgi’ in the usage section; ‘teh’ instead of ‘the’ in bringing up developer environment section.