Open mark-terminusdb opened 2 years ago
Presentation completed and shared. Attached here for convenience.
terminusdb-lunch-and-learn-technical-writing-v2.pptx
Legacy diagrams and uncompressed, editable diagrams currently in use are in the ppt below. Please ungroup diagram components to edit if required.
GitBook has pros and cons in almost equal measure. Use GitBook for minor edits to existing pages, not for major additions. However, using multiple editors also introduces delays and further challenges - please see Other future considerations further below. Some of the issues encountered:
Despite attempts to simplify, communicating TerminusDB in simple ways for all to understand continues to be challenging. Even the simplest data models can be defined in multiple ways, terminology continues to be used interchangeably across docs, tutorials, and the console. In particular, competence/familiarity with GitHub or GitHub-like concepts is assumed in the console. Some console inline/context-sensitive documentation or links to relevant pages of the docs site should be considered.
A very simple definition of TerminusDB, especially on the main website, would be beneficial. Consider something catchy and cheesy along the lines of TerminusDB - A Database with a Difference or a slightly more descriptive (but no less cheesy!) TerminusDB - A Database with a Transformative Difference
Reduce the number of tutorials and simplify where possible - please see my existing issue for further recommendations:
https://github.com/terminusdb/terminusdb-docs/issues/105
Several bug fixes and enhancements are recommended. Please see my issues created in the TerminusX repo:
https://github.com/terminusdb/terminusx/issues
Continue to simplify where possible - thinking in terms of a junior developer level at most as a baseline is recommended.
If possible in the future:
Technical writing and documentation development handover: