rigs-of-rods
rigs-of-rods copied to clipboard
RigsOfRods
Documentation for how to compile can be rather hard to find. What would be the best method of fixing that?
When I initially built Rigs of Rods, I had trouble finding the build instructions, as no section in BUILDING.md seemed to have it, and following its link to https://github.com/RigsOfRods/rigs-of-rods/wiki revealed a page which seemingly only had two links which did not have any detailed information on building. It turns out that I just needed to look in the sidebar, which doesn't usually have useful build instructions for most projects, but did in this instance, but because I did not expect it to have anything useful I ignored it. I would like to improve this experience for others who may want to build RoR, but which would be the best method to do so? Some possibilities:
-
Making a commit clarifying that instructions can be found in the side-bar, per platform? I have already made a set of two commits to do this (so far), but am unsure if this is the ideal method.
-
Make a dedicated sidebar on the wiki just for build instructions, then edit the previously mentioned commit to refer to that sidebar, so that if the wiki ends up with many more pages crowding the "Pages" section, the build instructions can still be easily found in their own, dedicated area.
-
Put links to the build instructions in the main wiki page instead? This is what I expected initially, but I am unsure how much it might interfere with the existing layout.
-
Put the build instructions in files in the repository? This would be how I would want to read instructions, since that means they are still available in the repository in case the internet goes down, but perhaps there is a good reason they are on a wiki instead. This method may also have the advantage of making it easier to move to a different Git hosting solution such as GitLab, if a need ever arises, since I believe the wiki is a GitHub feature, rather than a Git feature.
Another possibility (Number 5 I guess?): Have a dedicated Compiling page on the wiki, that links to all the other Compile pages, then have BUILDING.md link to it directly instead of the main page.
Which makes me think...
Possibility 6: Link all the Compile pages in BUILDING.md directly. That could make everything a bit easier to read, if it was laid out well, and make it take more space in BUILDING.md too, making it easier to find when skimming.
I think option 4 would be best, something similar to OGREs documentation: https://github.com/OGRECave/ogre/blob/master/BuildingOgre.md
I agree with option 4. Pretty straightforward to do and having offline access could be useful.
I'm really glad, because I definitely prefer 4!
Would having separate files for each OS work, e.g, BUILDING.Linux.md, BUILDING.macOS.md, etc? I believe I have seen it in some projects (but I forget which), and it would make it easier to copy the documentation over, since it is already in separate sections.
I think that separate files would be the best, that way you don't have to search the document to find the instructions your OS