docs: rewrite docs
This is a draft to rewrite the docs to make Cactus Comments easier to understand.
Language is difficult, and writing docs well can often be as hard as the code itself. So feel free to discuss the changes.
Also, my understanding of CC is still limited, so please check the new explainers carefully.
I reckon reading the diff is probably hard and the lot of red doesn't really help show what changed to what. I included more details in the commit messages. Though I suggest, before diving into the depths of the green/red mountain that is the diff, to try it out first and read the rendered version (‘npm run start’). This helps you get a rough sense of where things went and makes reading the diff much easier.
Blocked by !6 (closed). Actual changes start at commit 94f1d826
I tried to follow a few principles
Principles
- be simple
Simpler language makes for shorter sentences that are easier to understand. It helps avoid duplicate content because the reader can understand things with the first try. With avoiding duplicate content, reading becomes easier since it becomes less. Also there is a single source of truth that can be more easily remembered, discussed, and maintained.
- be logical
e.g. [..] features may still be missing. We would love if you helped contribute! instead of we strive to keep Cactus Comments [..] “production ready” [so] many features will be implemented later.
- be consistent
e.g. Cactus client and Cactus server pages, and Set up client and Set up server sections in Quick Start
- format well
use bullet points for a list, e.g. Prerequisites in Quick Start
use shorter links, e.g. check out this [example] here instead of [check out this example here]
- remove duplicates
single client embed snippet in Quick Start
no leads in favor of content itself
- correct page order
e.g. currently https://cactus.chat/docs/getting-started/quick-start/ is followed by "Hugo"
- no line breaks
Inserting line breaks manually requires constantly fixing them because changing words might make the line longer or shorter. This also pollutes diffs because now there can be changes in line breaks. Text editors should all support wrapping lines, so there is no need to format them like code.