I'll address the more tangential parts of this before getting back to the main subject of documenting mod compatibility.
Loriel wrote: ↑05 Jul 2018, 09:15
We should probably move the recently-added documentation on this ("So you want to help with documentation?", to which I am currently adding GitLab integration, as discussed elsewhere) to a "newbie developer" section, and replace with your much simpler options.
Agreed. When I added that, I just wanted to get the main part out and didn't really know how best to organize it at the time.
psi29a wrote: ↑05 Jul 2018, 07:19
Updating the manual/docs in the repo doesn't require a lot of work, nor your own fork nor learning about git/cloning/pushing/PR/MR. Just go to GL (even GH), create an account/login, click on the file you wish to edit, change stuff, click commit which will create a merge-request for you and then you get feedback on your contribution before it is merged. No need to install git nor know how to use git, just follow the dead simple instructions provided on either GL or GH.
GitLab even includes a Web-based IDE if you would rather use that. It really removes the need to learn about git/fork/pull/commit/push/mr(pr) regime.
I think the IDE makes editing here a bit better than when we were using GitHub, especially since (IIRC) GitHub still required the whole commit/push/pr workflow when editing. I agree that
updating/editing docs can be done online, but unless someone is super careful I think it's too easy to screw up the more complicated syntax if they're working online. I know we've had this discussion before, but I'm still of the opinion that anyone adding significant portions to the doc should have a Sphinx build environment locally so they can preview
everything. The online view gets most of the basic syntax right but view
this page for example. The whole TOC is missing and the :doc: link isn't formatted properly. I do want the barrier of entry to be as low as possible, but I also don't want to be fixing other people's syntax errors all the time. I think we'll be fine with your ultra simple guidelines for most people who just want to make a short change, we just need to remember to double check any special syntax.
psi29a wrote: ↑05 Jul 2018, 07:19
GL has a "wiki", all it requires is a user account... about the same barrier of entry as Wikipedia (with user account).
I am currently unable to simple edit the wiki, just suggest changes in the issue tracker. Will we need to approve every person who wants to contribute to the wiki as a developer? Or is this a one time permissions thing that just needs to be changed? (Or am I stupid and not doing something right?)
psi29a wrote: ↑05 Jul 2018, 07:19
All the things that don't belong in the docs, go to the GL wiki such as mod compatibility. That's already been discussed, more than once.
Yes, I should probably post a stickied blurb about this at the top of this subforum. Basically: if it's something official that needs to be accurate, we want to have some oversight via MRs so people can't change things willy-nilly. Plus it's version controlled, which will be helpful later. Hence RTD for these types of docs.
Anything that needs to have lots of community input or is not really crucial/official, we use the wiki. This is exactly what the mod compatibility page is, hence it's location on the wiki. This brings me back to the main topic...
You're right, it sounds like the workflow for the mod compatibility is severely lacking. In terms of wiki versus RTD, none of these problems would be solved via RTD and its crowdsourcing nature leaves it in the wiki for now. The best solution would be as Loriel says "a bespoke database", and also as you say, it would require significant effort and time. Perhaps there is a free tool online for this sort of thing that we can adapt? The problem probably being that it once again creates something that people need to make a separate account for, which we were hoping to limit.
Now I'm not trying to be contrarian, but I also don't personally see a need for mod testing on the whole. I know this is an idealized case, and it's in our best interest (certainly as public relations) to have this available for people, but the onus of saying whether something is compatible with OpenMW should be on the mod author, not us and our users. I just generally question the wisdom of trying to maintain an up-to-date database of compatible mods. I do worry that people will use this as a crutch to determine whether a mod is likely to be compatible instead of just asking themselves if it has complex scripts or not and if it worked with vanilla, because the answer to those questions usually is a pretty good indicator. And I worry about people asking about the status of their personal obscure pet mod and how annoying that will become. It seems futile to me, but if y'all want to do that and see value in it, I'm sure people will find it useful. (now I'll stop being crotchety)
If we really want to have a list of over 1000 mods, I think we're going to have to weigh the benefits of having a more robust system with the amount of time this will inevitably take. Perhaps an easier way would be to have a short blurb at the top of the wiki with the example code template that people should copy and paste, then add their details to. None of this solves the search problem, which is going to become even worse in GL I fear. Psi29a, do you know how to add search functionality to the wiki on GL? Because I didn't see anything on the few wikis I looked at from other projects. This is something that would be more easy and more functional if we moved to the database with type tags system.
It sounds like you may have been thinking of something that would automatically generate a small reST file that would get added to our RTD docs, but I don't think that's possible to automate, and has the same problems of being hosted in RTD anyway. Plus the bloat of that many files would be annoying to deal with. If we're able to integrate a web tool with this website, would a separate repo be a potential solution for this psi29a?
In terms of version control, we can't assume people will be on the current version, so we will have to require that as an entry field anyway.
Those are my thoughts for now anyway. It's going to be a PITA to migrate regardless of what we do, as is always the case with data without any built-in integrity :/