Introduce a better documentation collaboration method

[dmugtasimov]

(ATTENTION) The work on this task should not be started until explicit approval from @buckyroberts

The description is "work in progress" at the moment

Motivation

We need to collaborate on blockchain documentation posted on the website ( https://www.thenewboston.com/guide/introduction ). Process is not well-defined at the moment and involves to much manual work that is both error prone and time consuming.

Issues with the current process:

• We need to discuss documentation text adding the context comments but we do not have a tool for it. We use Google Docs occasionally, but it leads to having different versions of documents thrown here and there which hard to track.
• Changes made to Google Docs documents are being transferred manually to https://github.com/thenewboston-developers/Website repository which is error prone, tedious and time consuming. This also makes it difficult to track that every discussed change has been transferred to the git repository
• Currently documentation is stored in TypeScript source which makes it more difficult to operate on in terms of collaboration

Proposed solution

• Use a more documentation friendly format: markdown
• Use mermaid or IMG HTML tags for drawing diagrams
• Use HackMD for collaboration (has context comments and github integration)

Examples

Page	HackMD note	Committed to gihub	Note
Introduction	link	link	Plain text with headings
Glossary	link	link	Table
Blocks (img-tags)	link	link	Images provided with IMG HTML tags (also see unicode special character usage)
Blocks (mermaid)	link	link	Images provided with mermaid

[led76marx]

Here is my take.

Overall
This approach is a step forward that suites our needs:

• Treats "text as code", which is ideal for teams comprising devs / content authors
• Helps separate content from the rest of React stack
• Will eventually make content searchable when we implement a search functionality
• Unifies text with images/diagrams in one place, which will also help us in the future when we decide to localize content

Cons

• We lose (or need to update?) much functionality for components like tables and callouts that won't render in hackmd, and there is probably an amount of designers' and FEs' work in there; such elements will probably need to get manually converted or added
• Libraries like prettier will probably need to get deactivated for md content
• Cost (?)
• We lose or need to investigate how to design some (under construction) functionality re: pop-us for definitions in text or diagrams that won't render in hackmd and will need to manually handle in website code. Ref: Definition popups in text (tech docs) Developer-Portal#94 and Hotspot functionality in diagrams (images) Design#207

[dmugtasimov]

Other charting solutions for markdown do exist: https://gist.github.com/blackcater/1701e845a963216541591106c1bb9d3b

[dmugtasimov]

I converted several pages to markdown (please, see description for links). I converted "Blocks" page in two variants: with images linked and mermaid/other primitive used for producing images. Both approaches could be also combined. Also maybe if we produce more UML compatible diagrams it will be easier to use mermaid to draw them.

[wakawakathedev]

Personally I use a mix between draw.io and excalidraw if i need to map out a diagram.