Open illwieckz opened 2 years ago
Gireen
commented
2 years ago 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
commented
2 years ago (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":
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 | :no_entry_sign: nope | :heavy_check_mark: yes | :ok: reasonably easy |
| Static wikis like gollum | :heavy_check_mark: yes | :no_entry_sign: nope | :ok: I guess reasonably easy if you know git |
| Dokuwiki | :ok: storage format is raw text, which could be put in git without that much trouble | :heavy_check_mark: native | :no_entry_sign: ugh, neither the web interface or the text option would be user-friendly |
| Mycorrhiza | :heavy_check_mark: yes, stores its data in git natively | :heavy_check_mark: made to be edited from its web interface | :no_entry_sign: probably quite fazing for someone used to pretty interfaces, and the git workflow would probably be awkward |
| Modern wikis like BookStack or wiki.js | :no_entry_sign: nope | :heavy_check_mark: native | :ok: provided that you don't use noscript, they provide a quite nice user experience |
| Forge's wiki (e.g. GitLab wiki) | :heavy_check_mark: native | :heavy_check_mark: / :no_entry_sign: (depends) | :no_entry_sign: 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 https://github.com/Unvanquished/Unvanquished/pull/2091.
illwieckz
commented
2 years ago 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
commented
2 years ago 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
commented
2 years ago 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
commented
2 years ago 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.
The features of non-technical wiki are:
Features of the code wiki are:
illwieckz
commented
2 years ago 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
Our documentation is stored on the wiki: https://wiki.unvanquished.net/
Some major problems are (I may miss some):
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: https://github.com/Unvanquished/Unvanquished/pull/2108