Repository navigation
Improve "Contribute to the documentation" with web/github workflow #297
Description
As a part of my recent work, I have tried to make improvements to the "meta" section of the docs as it has come up in other projects.
For example I consolidated and added to the mkdocs build information.
That being said, I have been in contact with @Clutz450 -- someone who is qualified and prepared to make contributions to the docs for the first time but who is:
- previously unfamiliar with git and the github workflow
- not able to work with the msys2/console environment due to network restrictions
I think it would be good to further develop the "Contribute to the documentation guide in terms of the workflow for contributing to the docs purely from within the github web editor.
Because the private conversation I have been having with @Clutz450 is starting to generate useful ideas for the docs I'm hoping to move it here to the github repo where other conversations are happening.
Maybe we could have a new section focused on contributing via github that has some screenshots of the process?
@thatman84 I'm tagging you since we've been chatting about the direction the docs are going
Activity
[-]Improve "Contribute to the documentation" guide, incl. the web/github workflow[/-][+]Improve "Contribute to the documentation" with web/github workflow[/+]markwkidd commentedon Mar 20, 2019
One part of the web workflow section might describe the considerations for adding a new file, such as an image, if you are limited to the github web interface.
The tricky part here -- as with all of the more use cases for github that are more complex than editing the text of one particular page -- is that there is no way to avoid learning about git branches at this point.
In other words, @Clutz450, the changed document(s) need to be part of the same git "branch" as the images or other files you want to add to this repository.
Once all of the changes are made in your branch, in your forked copy of the repository, you submit a "Pull Request" for review.
Clutz450 commentedon Mar 20, 2019
Thank you @markwkidd for all your help so far and for inviting me to continue our conversation over here. Just to give you all an idea on my take on how I feel the guides should flow (at least for Windows) I had tried creating a video tutorial series where I started from the bare bones basics of downloading RetroArch to actually playing a game and try to teach the viewer something about why I was doing the things I was doing along the way so that they would one day be able to help themselves and figure things out on their own. If anyone is interested in watching them you can find them on my YouTube Channel here.
But with working 12 hour days and having a wife and 3 kids at home I just couldn't find the time to make the videos anymore. That is when I thought about trying to help out by updating the guides on the RetroArch docs. Mostly I will be working on this while at work during my slow periods (which is about 4 to 6 hours out of my 12 hour day) which is why @markwkidd said that I couldn't use the console environment due to my work locking just about everything down on these computers. I actually did download RetroArch onto one of my computers at work and after I unzipped it their antivirus program started going nuts and quarantined a bunch of files for some reason. lol. And while I also have like no GitHub experience either, it is something that I always wanted to learn and am slowly starting to figure some things out on my own. I hope that once I figure out how to make my changes to one of the guide sections that I can then do another basic tutorial on how to contribute to the docs and explain all the tips and tricks I have learned along the way.
So anyway, that's pretty much it. Sorry for the long and drawn out message. I'll try to not be so lengthy next time. Thanks again for all the help and I look forward to collaborating and working with you all in the future.
thatman84 commentedon Mar 20, 2019
thatman84 commentedon Mar 20, 2019
@Clutz450 i remember speaking to you about the videos. Hope you get on well here :)
My 1st thought on improving this part of docs would be to cover the routes to contributing.
I never use the web interface and am not sure of its limitations.
I used my local windows PC originally with desktop app then direct bash but have since killed all that and started with a Linux VM (I got a nice NAS and wanted to try it out). I just deleted my repo and started again which removes all my history i believe so not the "best" choice.
Briefly covering the different github interfaces would be a good 1st project.
Desktop app
OctopusButtons commentedon Jan 4, 2025
I recently added a guide for exactly that, but for contributing thumbnails via github.com on the web: https://github.com/libretro/docs/blob/master/docs/guides/roms-playlists-thumbnails.md (It's published to the libretro docs site as well, but beware of a current bug that breaks some sub-bullet hierarchies, therefore the doc page files on github is better)
I heavily and meticulously iterated that guide, so at this stage certain sections could be copied over to a similar guide for docs or cheats. Or the guide could casually be given as-is to an interested/motivated person with "Just follow that but replace the thumbnails part with "cheat code" or "docs text"" and most people would do OK. (In my opinion, docs/cheats are even easier than thumbnails, for the sole reason you can "pencil button edit" a little more straightforwardly in real-time.)
I think it's important work, because by establishing guides that people can follow, it potentially brings in a bunch of volunteers contributing. I'm pretty technical but I had to put in a few days in the past to figuring out the github.com process for contributing thumbnails. Even a determined person might give up when the initial obstacles are confusing and there's no documentation. So I'm trying to improve that in a few areas.