Pro tech writer here; help me improve docs!

herb_fargus

Just as a preface:

I've written the majority of the docs, whether or not I've done a good job is up to debate, I'm certainly open to those more talented improving what I've left off.

As you're probably aware mame is one of the most debated systems which being a complicated mass that emulates over 30,000 systems it makes sense. We've had countless discussions on the format for mame documentation as @markwkidd and others can attest.

Here are my concerns: Having the wiki be crowdsourced provides an inherent risk to the project when there are implications of tacit consent.

Eg:

We don't like telling people where to download ROMs. But we can tell you which ROM versions to get, a search engine may help

People will Read as:

we the retropie project won't Tell you where to find roms but if you were to go onto the internet this is what to look for wink wink nod nod.

The documentation should read as technical documentation, impartial, neutral.

Or the following line:

downloading games is illegal unless you also own legal copies of those games**.

This is quite frankly not true. This is dependent on the country but particularly in the US, even if you own a game, downloading being legally defensible is dubious at best.

Arcade ROMs go in /home/pi/RetroPie/roms/arcade.

There are lots of implications for this that a first time use won't understand and will inevitably cause issues in the future. For example let's say they put in roms from two separate sets in this folder, how will they know which emulator to use for each rom without going through and testing each one hoping it doesn't fail, it can lead to more confusion than it would solve than if they had just put the respective set in the respective rom folder.

When it comes to just getting mame working it's a simple process:

Each emulator requires a specific romset.

As far as understanding anything past that it's on the end user to do their homework which the other mame pages go into more detail on. Mame has never been simple and never will be due to the nature of what it is.

So hopefully I haven't scared you off with my input but I think it's important to consider all the aspects, particularly legal when it comes to emulation considering the current climate.

Darksavior

So someone that's not familiar that much with retropie wants to improve the docs...
Makes no sense, no matter how professional someone is in writing.

dankcushions

@woutertron well, i already hate your edits to that page :)

eg “reference set” is not a term used in romsets. it is a bespoke meaningless name given to a certain bunch of uploads of mame romsets on a certain website. it needs to be removed from our documentation.

you also wouldn’t be the first technical docs writer to have a go at simplifying the docs. i would implore you to get your changes reviewed here before applying them. i don’t want to put you off, though! they certainly can be improved.

my personal opinion is that they should have less explanations and more “do this”. arcade emulation is extremely simple until you stray from the path of least resistance. eg no one should using clrmamepro in a normal situation.

VictimRLSH

clrmamepro isn't very intuitive to use either. If you don't have your master rom set backed up and you do the wrong thing, clrmamepro will happily scramble your rom files into uselessness.

Maybe we need an application that will run a rom from a list by determining automatically what emulator that particular rom is best suited for, building the correct romset for it, and then running it using the best emulator. Not an easy undertaking either, but would solve a ton of problems and cut down on the headaches for new users to get arcade emulation working on Retropie.

woutertron

@herb_fargus Thanks for taking the time to respond! I hope my feedback didn't come across as overly negative. I'm hugely appreciative of anyone taking time out of their own life to write docs for the benefit of others.

I understand and agree with your comments about the legal aspects. I was trying to walk that line between illegality and still writing helpful, usable instructions. Please don't hesitate to roll back/forward any of my edits.

Also, I'll happily take the guidance of more experienced users when it comes to terminology (or anything else). It's exactly what I was asking for in my original post, in fact.

I hope my offer to contribute is taken in good faith and not seen as criticism or intrusion. For an online community to blossom, it should strive to create a welcoming atmosphere. An administrator telling a well-meaning newbie "I hate your contributions", quite apart from the quality of those contributions, is probably not conducive to that.

Let's agree we got off on the wrong foot and try again. Anyone who knows what they're talking about interested in pairing up with someone who knows how to choose the right words? :)

dankcushions

An administrator telling a well-meaning newbie "I hate your contributions", quite apart from the quality of those contributions, is probably not conducive to that.

@woutertron being passive aggressive is also not conducive to it.

i put a smiley after that comment. it clearly wasn't an attack.

herb_fargus

I've modified the arcade wiki page. open to feedback.

Clyde

@dankcushions said in Pro tech writer here; help me improve docs!:

An administrator telling a well-meaning newbie "I hate your contributions", quite apart from the quality of those contributions, is probably not conducive to that.

@woutertron being passive aggressive is also not conducive to it.

i put a smiley after that comment. it clearly wasn't an attack.

I don't think @woutertron meant to offend you any more than you did(n't) before, expecially as he/she otherwise went a great length to be not understood as criticising or intruding.

As an onlooker, I can see how both of you didn't meant your wording to be aggressive, but I can also understand how they could be misinterpreted as such. Alas, a smiley get's easily overshadowed by the message before it, and well-meant words can just as easily seen as passive aggressive. It's a sad truth about (not only) written communication.

Just advertising for seeing each others words in the best light. :)

markwkidd

@woutertron thanks for offering to write. As has been mentioned upthread, my own interest in working on the docs -- particularly the arcade emulator docs -- was what first got me involved in the forum community here.

I hope you plan to stick around! In addition to good advice from other posters, I'd suggest making it your mission to keep an eye out for Help threads related to your areas of interest -- if you aren't doing so already. Help threads are often where the "rubber hits the road" for the docs, so they are very useful in setting priorities for new documentation.

Because you seem specifically interested in making arcade emulation as accessible to users as possible would you be interested in helping create user documentation for mame2003-plus? We're in need of new docs for the core itself that go a step or two beyond what is in the RetroPie mame2003 docs (although those docs will be an important reference point).

If this sounds like it might be up your alley I'm glad to try to hone in on what would be most to your interest and most valuable to users.

grant2258

@dankcushions you seem to resist every change to anything. Maybe it's the way you come across. It certainly make things hard for anyone to make any progress with that attitude. I'll put a smiley at the end so that means you brush off you harsh attitude. I'll add a smiley at the end of mine so you k ow it's all in jest. :)

Lurker

Disclaimer: Many elements of what I wrote below are done in a way in various threads, and git hubs and redits etc., but it can be like searching for a particular Lego in a giant tub and then when you find it not knowing how it is supposed to be connected. Also I feel a little out of place commenting on how you should document a water park in which I am firmly splashing around the padded shallow pool with my floaties on.

With that said...

If I sit and think for a moment on documentation three different documentation paths come to mind and all three paths would exist together and in parallel to each other. This is coming from a position where I know a bit of practical things, a bit of theory and most of the threads here are far enough above my head that I might as well say "magic".

So Path #1
The kiddy pool. This documentation is more of a walk through document and a little explanation on what is possible. I would envision this document to be along the format of a collection of documents in which each works toward a small stated task and does not try to explain everything. The reader of the document would be able to follow the directions but does not need to understand what they are doing. This path is the most action oriented but the least informative.

Path 2
The technical section. This is the meat and bulk of the documents where the lengthy and specific details would be found. In here I would envision to seeing two parts. One part of specs and versions IE control map details, version updates, change log links etc. Part 2 would be more wordy and kind of a higher level of the Path 1 kiddy pool. Making recommendations of changes and such that the reader will either be able to follow or move back down to the kiddy pool for guided assistance as they figure it out.

Path 3
The high brained stuff.
Side note this is the area that I can comment on with the least authority as it gets into the "magic" description I mentioned above

This is where the advanced documentation would reside and users reading this would probably be at home in Path 2. This would be where I would expect to see documentation someone recorded about building an emulator or other advanced stuff. I could see this ground being were something vague and high end gets revised and boiled down to simpler instructions that are written into a doc for Path 1. Path 3 is the most vague but would also be the most indepth understanding of what is happening in the system.

An example: The big brains would document in Path 3 their notes on how they got ... oh I don't know, say "N64 New Tetris" to play smoothly. Then some one documents the details in Path 2 and someone who understands enough of what was done to distill that into instructions someone like me might follow in Path 1. Just as an example. You know ... in case you wanted something to work on.
Blink Blink...Blinkety blink blink

Bonus
The Class room. I can also see a bonus area of documentation where magic is explained.
What you do is magic.
I like magic.
I would like to learn magic.
How do I learn magic?
"Well first kid, it's not magic."
This type of documentation is more class room lecture and also more links to other sources and the rest would have as it is a guide to understanding computer science in relation to retro pie. Topics would be things like "What is a config file and how does it work" to "How an emulator is built" Rather than writing everything yourself you would find links to other explanation pages with some context about how that relates to retro pie.

cyperghost

@lurker That's a nice approach. But I think Path 1 and Path 2 are okay.
Path 3 and the other stuff will be discussed on platforms like github or as a question here in the forum for specific stuff.

So I would rename Path 3 to Further Links and this is a collection of forum links or links to github discussion. So other users may find a specfic solution. Just my 10 cents...

grant2258

@lurker here is something to help you understand mame roms

https://choccyhobnob.com/mame/demystifying-mame-roms/

woutertron

Thanks for the replies, everyone!

I do admit having been put off slightly by some earlier responses. But the newer ones help — I'm motivated to keep contributing. 👍

@markwkidd re: mame2003-plus docs: I'd be happy to explore that with you. Feel free to email me at me [at] wouter [dot] tech.

@Lurker Really like you sharing what you think the higher-level structure should be. Let me give you an idea of how I approach docs structure/organisation.

I tend to work from a taxonomy of 3–4 information types:

Concepts are discussions of things and ideas. They are aimed at understanding, rather than doing. Example: DAT Files: The Cornerstone
Tasks are lists of steps that get you from A to B. They are aimed more at doing, and less at understanding. Example: The different procedures under Transferring Roms.
References are collections of technical details (usually presented as a table) that you need while working. They don't follow a narrative; they just give you a bunch of related facts, which you'll refer to as you do other things. Example: MAME4ALL COMPATABILITY LIST [sic]
Tutorial is the fourth, less clearly defined type. Format-wise, they tend to borrow from the above types. They are aimed at learning-while-doing, and also at building confidence. A good tutorial not only teaches you new things, but also makes you feel good about the product and yourself. :) The Arcade Quick Start is an attempt at this, but I don't think it's quite there yet.

The point is to clearly delineate these types, i.e. keep them (mostly) separate. Why? Because people read docs for different goals, at different times.

When an experienced user is trying to perform a specific task, they want the plain steps, without a bunch of discussion about things they already know. But when a newbie is reading those same steps, they'll appreciate a link to a separate page that explains any concepts crucial to completing the task. Meanwhile, burying essential technical details in a tutorial will frustrate an expert who's just looking for that one parameter value, damnit.

It's all about organising the content in a way that it accommodates multiple use cases, and creating clear connections that enable people to follow the path that's right for them.

At this point, I would suggest the following:

Make an inventory of all the current content related to arcade emulation.
Label the different information types in that content.
Rewrite/reorganise so that both newbies and veterans can easily find the stuff they need.

We can do all this in a branch. If the result turns out well, we can extract templates that will help future contributors follow a similar structure.

Thoughts? I won't be able to do this alone, so it'd be really nice to pair up with someone who knows the ins and outs.

P.S. @herb_fargus thanks for editing my edits! I'll do my best to take a look and give feedback soon.

markwkidd

@woutertron is there any chance that you use Discord chat, or would be willing to?

There is a libretro/RetrArch Discord server where all of the active mame2003-plus developers (as well as a lot of other RA and core devs) can be reached. This is a direct link to the Discord channel, where I can be PM'd or tagged in #programming: https://discord.gg/C4amCeV

The other way that mame2003-plus developers tend to communicate is via github. It so happens that grant already has an issue stubbed out to talk about documentation related to input and input remapping: https://github.com/libretro/mame2003-plus-libretro/issues/329

That would be a great place to start if you're interested! :D