Technical Writing Handover

[mark-terminusdb]

Technical writing and documentation development handover:

• Process and best practices (All-hands presentation prepared.)
• Priorities and challenges (docs repo and products.)
• Recommendations.
• Q&A sessions
• Etc.

[mark-terminusdb]

All-hands presentation

Presentation completed and shared. Attached here for convenience.

terminusdb-lunch-and-learn-technical-writing-v2.pptx

Original diagrams

Legacy diagrams and uncompressed, editable diagrams currently in use are in the ppt below. Please ungroup diagram components to edit if required.

terminusdb-diagrams.pptx

Challenges and recommendations

GitBook

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:

• Slow (approx. 2 hours to create a page that can be created in approx. 30 minutes using an IDE.)
• Ctrl+Z or Ctrl+Y doesn't always work sometimes resulting in significant loss of work. Therefore, be careful when deleting:
  -- An image in a row of several images - sometimes all images are deleted
  -- A row or column of a table - sometimes the entire table is deleted.
  -- A code block in tab - the entire tab component is deleted including all other tabs and their content.
  -- A blank line - sometimes the entire paragraph following the blank line is deleted.

Complexity and GitHub awareness

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.

TerminusDB definition

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

Priorities

Tutorials

Reduce the number of tutorials and simplify where possible - please see my existing issue for further recommendations:

#105

Console and Product Explorer

Several bug fixes and enhancements are recommended. Please see my issues created in the TerminusX repo:

https://github.com/terminusdb/terminusx/issues

Simplify

Continue to simplify where possible - thinking in terms of a junior developer level at most as a baseline is recommended.

Other future considerations

If possible in the future:

• Consider using an alternative to GitBook. GitBook's peculiar markdown, editor issues, and API, CSS, and active content limitations can significantly impact productivity.