Create a "style guide" for how facts should be written

[Thunderforge]

Newspapers and other publications have a style guide in order to ensure that different writers create stories that are consistent in terms of grammar, punctuation, spelling, and other aspects. For instance, the Guardian and Observer style guide says to use the spelling "adviser" instead of "advisor".

While I don't think that we need to adopt anything close to a paper, I think that we ought to have a short set of rules for how fun facts are written in order to make them all seem consistent, despite coming from different authors. Some specific concerns I think should be addressed:

• What should be the length of fun facts (e.g. it should be between X and Y characters)?
• How should we write the names of games?
• What should the general tone of the facts be (do we want them to be more matter-of-fact or casual)?
• What topics are okay? Are we okay with video games on any platform, or would it just be console games?

There may be other things that need to be addressed as well.

[Thunderforge]

Here are my personal thoughts on these issues

What should be the length of fun facts (e.g. it should be between X and Y characters)?

This will require some experimentation to see what "looks good" when they are turned into screenshots. Right now, our shortest fact is 57 characters and our longest is 240, which feels like too big of a range.

How should we write the names of games?

Ideally, I would like for them to appear in italics (e.g. Devil May Cry started out as a failed Resident Evil game), but I think that will require modifications to the screenshot generation scripts. If that is impossible, then I would prefer having them in double quotes (e.g. "Devil May Cry" started out as a failed "Resident Evil" game.

Also, I think that the games should match the names as they appear on Wikipedia. For instance, we should have _The Legend of Zelda: Ocarina of Time_, rather than Zelda: Ocarina of Time. One of my pet peeves is seeing "Pokemon" rather than "Pokémon", so I would like to see that fixed.

What should the general tone of the facts be (do we want them to be more matter-of-fact or casual)?

Personally, I think that the should be matter-of-fact. As a contrast, there is a bar near me that has a trivia screen with quips at the end of the facts, like this: "The average American drinks 25 gallons of milk each year. That news keeps the dairy industry moooving!" I find that to be really tacky. Given that this is for a personal console that doesn't need to "grab your attention" the way that a public screen does, I think we should refrain from it.

Also, I don't think there is a good reason to use exclamation marks. Compare: "The PlayStation 2 is the best-selling console of all time." vs "The PlayStation 2 is the best-selling console of all time!". I don't know that we really need to present facts as "surprising" or emphasize them.

What topics are okay? Are we okay with video games on any platform, or would it just be console games?

I admit, I was a little surprised to see a fact about World of Warcraft, given that I was in a "console" line of thought. I have a weak vote for console games only, given that that is the vast majority of what RetroPie users will be using, but would be perfectly fine with any sort of video gaming facts, including those on the computer, if others would prefer that.

Please share your thoughts with these points as well. I'm just one guy's voice. I think that coming to a consensus on these points will result in more consistent facts that look like they could have been written by one person, despite having multiple authors.

[hiulit]

Great job! I also think that we should have a style guide of some sorts.

Here are my thoughts:

What should be the length of fun facts (e.g. it should be between X and Y characters)?

I think it would be good to have a fixed length, or at least a flexible length between two close numbers, but I also think it would be difficult to implement. Should we have people counting characters when writing a fun fact? Or maybe add some code to remove the fun facts that exceed a max characters length? I don't know...

How should we write the names of games?

Italics are not possible in this case. We'll use the double quotes. About the proper name of games. Yes, I'm with you. I'll check the names and I'll make the changes. Also, maybe using TheGamesDB instead of WikiPedia makes more sense?

What should the general tone of the facts be (do we want them to be more matter-of-fact or casual)?

It doesn't bother me that some fun facts have one tone and some other fun facts another tone. That said, I'm okay with removing the exclamation marks and try to filter out the ones that are more tacky.

What topics are okay? Are we okay with video games on any platform, or would it just be console games?

Hmm... I'm not sure about this one. When I created the Fun Facts! script I thought it would be good to have fun facts of any video game. But now that you mentioned it, when you are booting up your RetroPie, either being used in an arcade machine or in a console way, it doesn't make that much sense to see facts from games you won't be playing. So maybe we should stick to fun facts about games that can be played in RetroPie.

Summing up:

• All video game names must be enclosed in double quotes (e.g. "Sonic the Hedgehog").
• Check the names using the TheGamesDB.
• Fun Facts! aren't funnier even if they're written with exclamations marks. Don't use them.
• Tacky Fun Facts! aren't funnier either.
• Stick to Fun Facts! about video games that can be played with RetroPie (see supported systems).

What do you think?

[Thunderforge]

Should we have people counting characters when writing a fun fact? Or maybe add some code to remove the fun facts that exceed a max characters length? I don't know...

I figured that we would just check any PRs to make sure that they fit in the expected length range (and do a sweep over the existing ones to see if they meet the criteria). I don't think it's worth writing code to exclude facts that are checked in; just keep them from getting in in the first place.

Also, maybe using TheGamesDB instead of WikiPedia makes more sense?

Either is fine.

So maybe we should stick to fun facts about games that can be played in RetroPie.

That sounds good. Although I notice that DOS, classic Macintosh, Amiga, and anything that runs on ScummVM can be played with RetroPie, so we may have a few games that aren't "console" games. Still, it's a good guideline.

I'm good with your five bullet points. Perhaps we could add them to the readme, then just do a once-over for the existing fun facts to make sure they comply with the new guidelines.

[hiulit]

I've just released a new version v1.5.0.

I've revised fun-facts.txt following the style guide and I added the double quotes on name of the games and also removed a few facts. Feel free to check it yourself. If you find anything, you can comment it here but I'm closing the issue, as the main topic was adding a style guide and that's already been done.

Thanks!