47 lines
2.5 KiB
Plaintext
47 lines
2.5 KiB
Plaintext
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
|