Improving wiki writing coordination and reviewing

[illwieckz]

Our documentation is stored on the wiki: https://wiki.unvanquished.net/

Some major problems are (I may miss some):

• there is no direction on the writing effort,
• there is no effective review activity,
• it is forgotten,

Some cause of problems can also be solutions to other problems. As an example: the advantage of wiki is we can add things even if it's not perfect, but that's also an inconvenient as we may add content no one will use for various reasons like people not knowing it is added, or not being able to find it.

About the direction: we currently add pages and content in an almost random way (due to wiki nature, it being both good and bad), a bit of direction can diminish the bad side of wiki without altering the good side. One good example is the home page: we use the same since years, since a very long time, even myself only take the risk to only edit minor wording on it. Maybe we would need to do bold changes but who thinks about it and takes that risks? Currently, no one does.

About the review: I find the mediawiki talk page unusable for our use, at least currently it is if we don't integrate it in another process. They may become useful if there are some high-level talks in other places and they are only for very local talks. There is no notification, no easy way to be involved like we are with github repositories, etc.

About the wiki being forgotten: we don't link enough to it, we are not noticed about changes, etc.

Note: some interesting comments on the topic have been made there: Unvanquished/Unvanquished#2108

[Gireen]

I think it would help to revert the wiki homepage to something like the 2013 version
https://wiki.unvanquished.net/index.php?title=Main_Page&oldid=2731
It gives a better overview on the content.

[necessarily-equal]

(cc @bmorel) Ok, so as a bit of background, I did quite some research on wiki recently because we wanted to migrate from a dokuwiki at some other place. I arrived to the conclusion that we have a fundamental problem of "choose two out of three":

• We could have something that versionifies with git
• We could have something that has a web user-interface
• We could have something that has a convenient web-interface

I didn't find a tool that could tick all three. That is, there are tools that can be used with a git backend and a web interface but aren't convenient, tools that have a convenient web interface but next to no way to be edited in a text editor, and tools that are made to push a wiki from a git repository but are quite confusing to use for people who don't know git (and github or gitlab or $other).

Software	git / text-editor compatible	web-interface that allows edition	convenient
MediaWiki	🚫 nope	✔️ yes	🆗 reasonably easy
Static wikis like gollum	✔️ yes	🚫 nope	🆗 I guess reasonably easy if you know git
Dokuwiki	🆗 storage format is raw text, which could be put in git without that much trouble	✔️ native	🚫 ugh, neither the web interface or the text option would be user-friendly
Mycorrhiza	✔️ yes, stores its data in git natively	✔️ made to be edited from its web interface	🚫 probably quite fazing for someone used to pretty interfaces, and the git workflow would probably be awkward
Modern wikis like BookStack or wiki.js	🚫 nope	✔️ native	🆗 provided that you don't use noscript, they provide a quite nice user experience
Forge's wiki (e.g. GitLab wiki)	✔️ native	✔️ / 🚫 (depends)	🚫 the web interface is typically awkward if it exists, and many would disagree that editing in a command line to then meddle with branches and remotes and forks is something they want

So the real question is what are we willing to compromise on? I am really not sure that we want a repo that is in git, if that means we cut out people like SuperDupont or lautre from participating in the wiki.

I must say I haven't explored wiki/doc generation from code, but I'm pretty sure it'll have the same problem of cutting out people if they don't know git, only worse because they would also need to navigate the code which is unfortunately dreadful for many.

Not to say code documentation makes a lot of sense to have in code, that's another issue. For the record, I think @DolceTriade would like luadoc for the LUA bindings, as there were such annotations in Unvanquished/Unvanquished#2091.

[illwieckz]

Not to say code documentation makes a lot of sense to have in code

Yes, they are multiple kinds of documentation. We can have autogenerated documentation from handwritten code comments and hand written documentation for things explaining architectures, tutorials, etc.

Not a wiki but may be good enough, Sphynx (also supports markdown with plugin): https://www.sphinx-doc.org/en/master/ use by https://docs.python.org/3/ and readthedocs documentations like https://borgbackup.readthedocs.io/en/stable/usage/general.html .

About "choose two out of three" problem we also make heavy usage of one feature: MediaWiki templates.

[illwieckz]

Among git based wiki I also heard of gitit: https://github.com/jgm/gitit

This page lists Realms as Git based, it looks like there is a web ui: https://github.com/scragg0x/realms-wiki

[illwieckz]

On the coordination topic, one thing we need (but that's not a requirement for the wiki software) is a convenient way to track requests and tasks, being things wanted to be done, or things needing to be corrected. Like an issue tracker dedicated to the wiki.

We need to be able to set objectives, track progression, report problems and filter them.

[DolceTriade]

Imo, it's sensible to have two locations to store information: one geared towards developers who can (or want to learn) code, and one for the general community of server hosters, admins, players, and artists.

• We should be commenting code using some autogeneratable format. Portions of the sgame are already documented this way. This information should be stored in the git repo itself.
• Docs about setting up a developer setup, PR process, code style, docs about various engine and gamelogic subsystems should be stored in the git repo itself.
• Day to day operations around administering a server (docs on how to write scripts, cvars, etc) should be in a non-technical wiki
• Info about playing the game should be in a non-technical wiki
• Information about creating assets for Unv (maps, HUDs, models, icons, etc) should be in a non-technical wiki

The features of non-technical wiki are:

• Low barrier of entry (ie, integration with SSO, web based editor)
• Revision history and strong moderation tools
• Self hostable

Features of the code wiki are:

• Stored in git
• markdown, or some other reasonable text based mark up language
• Autogeneratable into some nice HTML UI.

[illwieckz]

That looks good. About documentation in git repo, we can also add some readme as some folder index to document what kind of code the folder is purposed to store, like we started to do in engine repository:

https://github.com/DaemonEngine/Daemon/tree/master/src/engine#readme