[FS19] XML Documentation Project -- Help Needed

barrowwight
Posts: 8
Joined: Mon Jul 13, 2020 12:39 am
Contact:

[FS19] XML Documentation Project -- Help Needed

Post by barrowwight »

A few weeks ago I posted a question on the forum asking if there was any reference for the Game's XML files (see it here: viewtopic.php?f=895&t=169452), as I wanted to learn how to start modding, but could not wrap my head around how to write XML files for the game.

I learned that there was not any existing reference for the XML files, so I decided to start working on my own documentation, and release it using GitHub so that other people can contribute to the documentation. Furthermore, I decided to generate some XML Schemas to help modders validate their XML files.

It is largely incomplete at this point, as I do not know what a good portion of the XML elements do, but by making it open source, I hope to be able to make the documentation a community effort.

Further details about the project layout and how to contribute are found in the README.md and CONTRIBUTING.md files in the repository.

GitHub repository URL: https://github.com/Marsfan/Farming-Simulator-Mod-Doc
Documentation Website URL: https://farming-simulator-mod-doc.readthedocs.io/
Help out with creating high quality modding documentation at https://github.com/Marsfan/Farming-Simulator-Mod-Doc
User avatar
Mrbrutal
Posts: 9
Joined: Tue Nov 20, 2018 1:18 am
Location: Slovenia
Contact:

Re: [FS19] XML Documentation Project -- Help Needed

Post by Mrbrutal »

This is a great idea and something that is severely lacking in the modding community. I feel like everyone is just tilling their own garden as it were (pun intended) and not very willing to share the information they learn along the way.

I would love to contribute, but it seems that to do so requires a lot of work and knowledge, which is I'm sure a hassle for a lot of people. (As I see no real progress has been done in the recent months)
There should be an easier way for people to contribute for this to succeed.
barrowwight
Posts: 8
Joined: Mon Jul 13, 2020 12:39 am
Contact:

Re: [FS19] XML Documentation Project -- Help Needed

Post by barrowwight »

Awesome, someone replied to the post. I have been pretty busy with other stuff for the past few months, and have not had time to work on the documentation (or even play FS19). Do you have any recommendations regarding how to make it easier to help out?

If you can't really figure out how to edit files, feel free to just create issues (see the tabs on the github page) to propose changes, and I will either add them myself, or tell you how to add them.

I agree that the repository looks pretty overwhelming, but I think it is simpler if you break it down, so here is summary of the folders

TLDR: Most people will want to edit the docs folder, modders might like the stuff in the schemas folder.

The most important folders are the docs folder and the schemas folder.

The docs folder is where the actual documentation is stored. The documentation is written using a special kind of file called reStructuredText that allows for a user to specify things like heading and lists in a plain text file. Any changes to this folder on GitHub will automatically update the documentation on the website. Each file corresponds to a page on the website. Currently there is one file for each kind XML file used by the game, and most of them need documentation.

The schemas folder is my attempt to write what are called XML schemas. Basically they describe what should be in a xml file. This allows advanced editors to display warnings if something about a XML file that the you have written seems wrong. XML schemas are not fun files, and are really complicated. I think they work for just about any FS19 XML files in the base game, but I am not 100% sure. I would like to set up a method that tests them against a bunch of mods that we know work, to verify that the files are correct. I don't expect a lot of people to edit these files, due to how complicated and annoying they are (can you tell I don't like them?)


Other stuff
  • The .github folder stores some specific files used by GitHub to configure things like templates for creating issues.
  • The utils folder is just some scripts I used to help generate the XML schemas and clean them up. They probably won't be used unless someone wants to try to document a different Farming Simulator game.
  • .gitignore is used to tell GitHub to not sync certain files to the server. It's not important if you are not going to be doing anything with the utils.
  • CONTRIBUTING.md is just a text file that lays out guidelines on how to help out.
  • LICENSE.md is legal stuff. Basically it says you can't try to copyright this project, and if you want to use it in your own separate project, you need to make it clear that you used it and you have to disclose what changes you made to the project, but you don't have to share all of your project.
  • README.md is the text that appears at the bottom of the github page
Help out with creating high quality modding documentation at https://github.com/Marsfan/Farming-Simulator-Mod-Doc
User avatar
Mrbrutal
Posts: 9
Joined: Tue Nov 20, 2018 1:18 am
Location: Slovenia
Contact:

Re: [FS19] XML Documentation Project -- Help Needed

Post by Mrbrutal »

Hey, thanks for the detailed description. I am quite familiar with the git and the structures of repositories, and files I was just saying that a lot of modders are probably not and this would not make it any easier to contribute. I guess a simple wiki software or something like that would be simpler. (But that's another story)

I think that checking if a mod has everything done correctly, is already done by the tool the Giants provide here:
viewtopic.php?f=1014&t=173608

Ok, say I want to add information about the <suspension> tag in the vehicles XML file. Where would I go and place that?
Or where would I place information stored in the modDesc.xml file? I feel like those are missing.
barrowwight
Posts: 8
Joined: Mon Jul 13, 2020 12:39 am
Contact:

Re: [FS19] XML Documentation Project -- Help Needed

Post by barrowwight »

Mrbrutal wrote: Sat Aug 28, 2021 1:07 pm I guess a simple wiki software or something like that would be simpler. (But that's another story)
Good point. I never though about a wiki.
Though there are two reasons why GitHub suited my case better.
  • XSD files are not best suited for a wiki.
  • By using GitHub, edits to the documentation can be verified before allowing them to be published.
Mrbrutal wrote: Sat Aug 28, 2021 1:07 pm I think that checking if a mod has everything done correctly, is already done by the tool the Giants provide here:
viewtopic.php?f=1014&t=173608
Interesting. Seems that came out after I set this up. I see that as working along side the XSD file method, as XSD files allow for real-time checking within the editor, while the Giants tool is the final stage verification.
Mrbrutal wrote: Sat Aug 28, 2021 1:07 pm Ok, say I want to add information about the <suspension> tag in the vehicles XML file. Where would I go and place that?
As that is a parameter in the FS2019 XML file vehicle.xml, you would add documentation for that in Farming-Simulator-Mod-Doc/docs/FS2019/XML/vehicle.rst
Mrbrutal wrote: Sat Aug 28, 2021 1:07 pm Or where would I place information stored in the modDesc.xml file? I feel like those are missing.
Looking at the repo, I don't seem to have a file for modDesc.xml documentation, however, such a file would be titled modDesc.rst and go in the Farming-Simulator-Mod-Doc/docs/FS2019/XML/ folder.
Help out with creating high quality modding documentation at https://github.com/Marsfan/Farming-Simulator-Mod-Doc
CptTractor
Posts: 18
Joined: Tue Oct 19, 2021 2:13 pm

Re: [FS19] XML Documentation Project -- Help Needed

Post by CptTractor »

I've stumbled on this a couple times over the last couple weeks. It's interesting. The current state of documentation for a 10 year old game is an absolute travesty. I can hardly believe the poor state is not due to nefarious intervention because it's so absolutely, stunningly poor in contrast to any other community. I don't even see threads about the most common things in the german side either.

An issue I have here is that I do QA and documentation and I cannot understand what you're trying to do enough to explain it to someone who's well versed with git. I'm staring at a wall. We've got to make it easier for people to contribute to accumulating and sharing knowledge otherwise we're just going to spend another 10 years with every single person who downloads a mod and finds that it doesn't work going through the exact same steps of reinventing the wheel. I really cannot fathom how this community got to this stage.
sernique
Posts: 2
Joined: Sun Nov 28, 2021 7:29 pm

Re: [FS19] XML Documentation Project -- Help Needed

Post by sernique »

Good luck with that project, i see you're still maintaining it.
I would love to see Lua documentation from Giants being as professional as this.
janie2
Posts: 4
Joined: Thu Jan 13, 2022 8:56 am

Re: [FS19] XML Documentation Project -- Help Needed

Post by janie2 »

Really cool project . Best of luck.
Post Reply