Is there a better way to document mod compatibility?

All discussion on project related documentation including source docs, manuals, and tutorials go here.
User avatar
Thunderforge
Posts: 503
Joined: 06 Jun 2017, 05:57

Is there a better way to document mod compatibility?

Post by Thunderforge »

I've worked quite a bit on the Morrowind mod compatibility status page on the current wiki and now it categorizes over 1000 mods. As we've talked about moving it to GitLab's wiki, I'm starting to wonder if there is perhaps a better way to document and organize mod compatibilities.

There are a number of issues I see with the current approach:
  • Searching for mods is difficult (you have to use the general wiki search)
  • Mods can only be in one category (is The White Wolf Of The Lokken Mountain a quest mod, a companion mod, a house mod, or something else?)
  • The MediaWiki table syntax has a learning curve that is difficult to grasp (at one point, a Discord user asked me to create a bunch of empty entries for mods they wanted to add because they had trouble figuring it out)
  • Formatting for entries, especially testing dates, are inconsistent
  • There isn't a way to easily link to related mods (e.g. Graphic Herbalism - Expanded Sounds Compatibility Patch doesn't link to Expanded Sounds Compatibility)
Of these issues, I think that searching and organization are probably the biggest two issues for me.

While the MediaWiki table syntax would be addressed with a migration to GitLab's wiki, I'm wondering if maybe we should take a step back and ask: is there is a better way to document all of these mod compatibility notes?
Loriel
Posts: 179
Joined: 28 May 2015, 00:44

Re: Is there a better way to document mod compatibility?

Post by Loriel »

I too have contributed quite a few entries, and I agree the current system is showing serious signs of strain.

As the number of entries has increased, it has become difficult to find a specific mod. One of the potential problems is naming inconsistency - should the author's name be included (eg Abot's Water Life), should leading articles be included (The White Wolf etc)?

I don't find adding a new entry difficult - I simply copy/paste an existing entry into the right place, then amend the details, so I don't have to worry much about the formatting.

I don't worry too much about date format inconsistencies, because testing a large mod isn't going to be completed in a single day, perhaps not even in a single month. There is a potential benefit in enforcing strict formatting, so that searching by date is possible, for example to highlight reports over x years old for possible re-testing. But using OpenMW version number is probably a better alternative.

A potential solution for these problems - write a bespoke database, which could automatically handle things like formatting and validation, and add some of the missing features like multiple categories and links. But the work involved in setting it up would be substantial.

Loriel
User avatar
Thunderforge
Posts: 503
Joined: 06 Jun 2017, 05:57

Re: Is there a better way to document mod compatibility?

Post by Thunderforge »

One alternative I've thought of is to do something along the lines of Homebrew's formula and cask repositories. Essentially, there is a file for each mod that contains metadata information like the following (I've used YAML format for the example):

Code: Select all

name: My Mod
author: Me
downloadURL: http://example.com/myMod
categories: [quests, npcs]
requirements: [Tribunal, Bloodmoon]
versions:
    - version: 1.0
      openMwCompatible: No
    - version: 1.1
      openMwCompatible: Yes
The repository would include a script that checks for validation, and using Travis-CI or an alternative, we would run that to verify that all new data added by PRs are properly formatted.

Then a bare bones web application is built that parses all of these metadata files and provides for a way to easily search for mods, and to look for mods in different categories (e.g. all the NPCs mods).

Pros:
  • Version control means that there is no need for a "tested date" or "author" field that we currently have, and there is a record of previous testers
  • Mod compatibility records are added by pull requests, just as our current code is done, which means that learning curve is minimal and is transferrable to other contributions
  • Having each mod in its own file means that everything is scalable
  • Web app designed around parsing this means that we could display and search for the data however we want to (e.g. show only OpenMW-compatible companion mods). Could also add a REST API to add third-party things to interact with it.
Cons:
  • Setup for this will be time consuming, both in transferring existing wiki data and in setting up a web app
  • We would be maintaining a separate repository and a web app that is likely written in a different technology stack than what OpenMW is written in
  • The web app would have to be hosted somewhere
User avatar
Starsheep
Posts: 54
Joined: 06 Jun 2018, 16:09

Re: Is there a better way to document mod compatibility?

Post by Starsheep »

Setting up a gitlab account, learning git, cloning, committing, pushing, learning how to make a PR makes for quite a big barrier of entry for a non developper contributor. This learning curve is steeper than editing a wikimedia entry.

The recent move to use the base user manual to RTD with sphynx has the same issue for non-coder contributors.

But I can't think of any better idea for this matter. The point being that developer tools should be kept for code contributions and that if documentation/reference needs to be sourced from a larger crowd, it preferably should be through user-friendly tools.
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Is there a better way to document mod compatibility?

Post by psi29a »

Starsheep wrote: 05 Jul 2018, 01:02 Setting up a gitlab account, learning git, cloning, committing, pushing, learning how to make a PR makes for quite a big barrier of entry for a non developper contributor. This learning curve is steeper than editing a wikimedia entry.

The recent move to use the base user manual to RTD with sphynx has the same issue for non-coder contributors.

But I can't think of any better idea for this matter. The point being that developer tools should be kept for code contributions and that if documentation/reference needs to be sourced from a larger crowd, it preferably should be through user-friendly tools.
I do believe you are going the long/hard way around... it's actually a lot simpler than that.

GL has a "wiki", all it requires is a user account... about the same barrier of entry as Wikipedia (with user account). 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.

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.

As for an alternative; I'm open to other online tools for handling mod compatibility which is to be very important.
Loriel
Posts: 179
Joined: 28 May 2015, 00:44

Re: Is there a better way to document mod compatibility?

Post by Loriel »

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.

Working on some MRs for that now.

Loriel
User avatar
Ravenwing
Posts: 335
Joined: 02 Jan 2016, 02:51

Re: Is there a better way to document mod compatibility?

Post by Ravenwing »

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 :/
User avatar
psi29a
Posts: 5355
Joined: 29 Sep 2011, 10:13
Location: Belgium
Gitlab profile: https://gitlab.com/psi29a/
Contact:

Re: Is there a better way to document mod compatibility?

Post by psi29a »

It seems that GL (like GH) requires that users have 'developer' level permission to create and modify the wiki.
https://docs.gitlab.com/ee/user/project/wiki/
https://docs.gitlab.com/ee/user/permiss ... and-issues

We can kinda work around this here:
https://stackoverflow.com/questions/106 ... 7#11481887

It's pretty wonky, but it works. It shouldn't be this hard... and GH and GL suffer from it. It allows for people to create PR/MRs to update the wiki.

I also have no problem giving you developer lever access to manage/curate the wiki anyway, but it doesn't solve the issue of people wanting to join and just add/improve the wiki.

I'm also backing away from Mod Compatibility in the wiki (on mediawiki and GH/GL) and in the docs. There has to be a better way and I'm open for suggestions.

I was thinking something like an online collaborative database. I remember we experimented with Google Forms in the past to some success:
https://www.google.com/forms/about/

Does this fit our requirements?
* ease of use and contribution
* can be easily copy&pasted all over the internet
* history management
* clear and simple layout
* can be exported/imported to our RTD (for releases)


Some other options:
https://www.lifewire.com/best-free-onli ... rs-3486264
https://en.wikipedia.org/wiki/List_of_c ... d_software
User avatar
Thunderforge
Posts: 503
Joined: 06 Jun 2017, 05:57

Re: Is there a better way to document mod compatibility?

Post by Thunderforge »

While Google Forms is dead simple, which is a huge plus, I see two big issues with it:
  • Somebody has to review the submissions to make sure we don't get junk in there or duplicates (how much work will that be?)
  • Updating records can be kind of messy (do I submit a new form? How do I get rid of the old record?)
I agree with the sentiment earlier that it's less than ideal for the OpenMW project to be maintaining mod compatibility listings. It's a pity that Nexus Mods doesn't have a tag or something to indicate OpenMW compatibility; otherwise we could use their API to just find mods tagged with that.
User avatar
AnyOldName3
Posts: 2666
Joined: 26 Nov 2015, 03:25

Re: Is there a better way to document mod compatibility?

Post by AnyOldName3 »

We could always talk to the Nexus people about that. If they don't respond to an email (which they probably will), I might be able to get Tannin to put us in contact with the right people as he's responded to discord DMs from me before when it's been about Mod Organizer's guts, and he works for the Nexus now.
Post Reply