Pro tech writer here; help me improve docs!

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