devdocs/specs/core-documentation.txt

@@ -0,0 +1,46 @@
+Documentation
+
+HELP MANUAL POINTS TO CONSIDER 
+
+ONBOARDING
+    - The manual and/or guides and/or built into UI guided help needs to answer all the specific questions people have when onboarding
+        - For example a section for technicians, dispatcher, each business role and then under that answers to basic questions:
+            - How do I see my workorders that are open
+            - How do I see who is where today
+            - How do order inventory
+    - The old manual and guide weren't job and task oriented so it doesn't directly answer questions people have, 
+        it just shows how to use features which isn't the way people approach it when familiarizing themselves.
+
+PRE-SALES
+    - Similar to onboarding but a higher level view, just basically answering the questions "Can it do XXX??"
+    - Perhaps it's the same as onboarding but you have to click through for ever increasing detail so you can abandon once your question is answered 
+
+
+
+
+
+
+- User docs and manual written in Markdown format (commonmark).
+- MKDOCS tool used to generate static html "site" for docs
+- Docs versioned into folders by major/minor version, so different docs for 8.1 and again different for 8.2.  Patch revisions don't change docs.
+- Static docs site incorporated into AyaNova backend so can view the docs for that release inside it directly.
+- Docs written in parallel with development as per agile principles so as soon as a feature is added it's documented as well.
+
+## Markdown for documentation
+- [Commonmark cheat sheat](http://commonmark.org/help/)
+- [Commonmark testing 'dingus'](http://commonmark.org/help/)
+- Convert markdown to other formats with this tool http://pandoc.org/
+    - Useful for standalone docs maybe
+
+- Auto generate a static site from markdown docs with this developer tool: http://www.mkdocs.org/
+- Material theme for MKDOCS https://squidfunk.github.io/mkdocs-material/
+- MKDocs WIKI (themes, solutions to tricky things etc) https://github.com/mkdocs/mkdocs/wiki
+
+** MKDOCS **
+- HOW TO RUN IT: python -m mkdocs serve to run the server, python -m mkdocs build to build the site
+- package is tragically out of date on my debian, have to install manually
+- Already had Python 2.7.13 (mkdocs page says 2.7.2 in it's example but 2.7 is ok)
+- didn't have PIP so have to get that, selected python-pip in synaptic (v9.0.1-2)
+- Installed mkdoc by running pip install mkdoc
+- apparently not in path have to preface command with python like so: python -m mkdocs new ayanova
+- Also installed the Material theme which looks a lot nicer