I'd like to improve the Github documentation -- thoughts?

Ruffle80

Is it someone on this board who is responsible for updating the Retropie documentation on Github?

I'm somewhat new to Retropie, and have found the Github documentation to be extremely helpful. However, it's not as great as it could be. I frequently have to troll other websites to find out tricks that aught to be right in Github. It seems silly to be having to go all over the internet when it could all be on a single Github page.

A few examples....

For the PSP emulator, it requires an Xbox controller
The Sega CD emulator requires that a BIOS be installed. The BIOS is indicated on the page, but it's not made crystal clear to a newbie that you must install the BIOS or the games won't work. Perhaps that's my main criticism -- that the documentation is not geared towards newbies at all.
MAME ... what can i say about this. I've read 30 or 40 pages of blogs, websites, and messageboards. Each one has a different tidbit that i didn't know, most of which are not on the Github pages. Folks all over the internet are asking the same damn questions about romsets and versioning because they're so confused.

So part of my job at a software company is to document our systems. I feel I could improve the Github documentation if folks are interested.

My plan would be to troll these outside websites (as time allows) and try to bring all the useful information into the Github pages so that they are more all-encompassing. Thoughts? Another good reason to do this is that there's quite a lot of instances where the Github pages link out to external sites, which is dangerous, because those pages could go dead at any time, never to return -- the information is then lost.

Darksavior

I don't see any reason for your additional input into the retropie github wiki. Your examples are easily explained:

PSP does not require an xbox controller. I can use it on my snes pad just fine. There is no controller requirement. As long as it has enough buttons.

For segacd and mame questions, this is documented in:
https://github.com/retropie/retropie-setup/wiki/Sega-CD
https://github.com/retropie/retropie-setup/wiki/arcade

The instructions for segacd even tell you where to place the bios.
The instructions for mame and fba tell you what romsets they require.
In the 30-40pages you supposedly read, maybe you should've headed to the retropie github first.

herb_fargus

@ruffle80 I've done the majority of the documentation, and I'll be the first to admit there is always room for improvement.

It's a hard balance to provide a standard template/framework whilst including relevant information. What I don't want the documentation to turn into is a newbie guide written like a walk through, retropie can be as simple or as complicated as people want it to be and the documentation will never cover all the use cases.

I've tried to keep the pages as objective as possible without adding extraneous tangents or caveats. Eg with the Sega CD there may be cases some games work without a bios but by having the bios there it's implied as a requirement. As is the case for many of the systems, though some bios can be optional as some systems have emulated bios. Again... It's a rabbit hole. Especially once you get to Mame.

No amount of documentation will solve Mame, that's something people just have to get their hands dirty on. The basic idea is just that people need to have a matching romset for the emulator they are using. The vast majority of people that have problems fail to understand that point.

Anyways I'm open to suggestions on improvement, wiki is editable by anyone but I'd like to keep it as standardised and as efficiently worded as possible (unlike my posts!)

dankcushions

@ruffle80 said in I'd like to improve the Github documentation -- thoughts?:

Is it someone on this board who is responsible for updating the Retropie documentation on Github?

you, me, and everyone with an internet connection :)

I'm somewhat new to Retropie, and have found the Github documentation to be extremely helpful. However, it's not as great as it could be. I frequently have to troll other websites to find out tricks that aught to be right in Github. It seems silly to be having to go all over the internet when it could all be on a single Github page.

A few examples....

For the PSP emulator, it requires an Xbox controller

no, it doesn't?

The Sega CD emulator requires that a BIOS be installed. The BIOS is indicated on the page, but it's not made crystal clear to a newbie that you must install the BIOS or the games won't work. Perhaps that's my main criticism -- that the documentation is not geared towards newbies at all.

fair. that seems like a simple update. do it!

MAME ... what can i say about this. I've read 30 or 40 pages of blogs, websites, and messageboards. Each one has a different tidbit that i didn't know, most of which are not on the Github pages. Folks all over the internet are asking the same damn questions about romsets and versioning because they're so confused.

the github pages definitely contain ALL the information you need for MAME. there is a LOT of nonsense and overcomplicating of MAME throughout the internet. i've seen people claim the documentation is bad, but fail in explaining what it lacks and how it can be improved, yet still being concise yet complete. be VERY careful here :)

So part of my job at a software company is to document our systems. I feel I could improve the Github documentation if folks are interested.

My plan would be to troll these outside websites (as time allows) and try to bring all the useful information into the Github pages so that they are more all-encompassing. Thoughts? Another good reason to do this is that there's quite a lot of instances where the Github pages link out to external sites, which is dangerous, because those pages could go dead at any time, never to return -- the information is then lost.

my worry is: there is a LOT of nonsense and bad information all over the internet about retropie. i feel you need to know quite a bit about retropie and emulation to understand what deserves to go into the documentation.

Zigurana

If you feel you can contribute to the documentation, please make a proposal, and it can be judged on it's merits.

Ruffle80

I definitely don't want to step on anyone's toes, and i don't want to put in information that's wrong either. Let's face it, I've been working with Retropie for a year, and i don't know everything -- I freely admit this.

I realize that Github is a wiki, and i technically can go in at any time and edit it, but i don't want to do that if folks aren't cool with this.

So i promise not to make it into a "newbie guide" or do any massive overhauls since i don't know as much as you guys probably do, but i assume folks are ok if i go in an clean up some wording and make some items a bit more clear? Basically, just minor items.

meleu

@ruffle80 yeah man! Go ahead please! ;-) if you post here about your changes it would be kind.