Create a plan for the documentation

[toby63]

As mentioned before it is planned to:

• move the documentation from the wiki to the website and github repos.
• renew the documentation as some of it is a bit old and maybe outdated
• In addition I would also like to shorten and comprehend it.

I would like to have a more concrete plan for the process.

This mostly involves:

• Structure
• Content
• Writing Style

Structure is important to decide which content should be on one page or seperate pages for example.
For the content it should be decided what content we want to have (with a priority, e.g. must-have, good-to-have etc.) and how the content should look like.

I guess there are also some more factors and ideas.

---

Related to:

• WIP: DOCS: Add Userguides to the documentation. #4628
• [Discussion] C++ guidelines / tools #4261

[Krzmbrzl]

I think the structure and writing style are up to the first ones who actually write docs for the website. Once we released the first snippets onto the website, that should be what we try stick to.

[toby63]

I disagree, though it seems I am the first one 😄 , at least for user documentation etc.

But I guess it will be discussed in each pull request then.
I was thinking about clearer Writing Guidelines, to achieve for example: shorter and more focused texts.
No offense but in the wiki I find very long texts.
For people who want to read a book that might be well formulated, but for people who want to search quickly for information, it is rather unuseful.

[Krzmbrzl]

Putting up too many rules that basically dictate how every single word has to be written raises the entry barrier (quite a bit) and thus probably keeps a few folks from contributing.
Besides I think the time needed to set up these rules is better spent actually (re)writing documentation.

What I would deem reasonable (and probably useful) are very rough and general guidelines like (for example)

• Each page should start with a small summary (abstract) of the documented aspect containing only the most important information
• Try to stay as short and concise as possible when writing documentation. If you want to be more verbose, consider writing a guide instead

[toby63]

That's the idea.

[toby63]

mumble-voip/mumble-www#125