Clean up doc files

Users are still confused by our root directory sometimes, especially when it comes to compiling. I set out to clean it up a bit by moving doc into a subfolder where we can, but took the opportunity to move things to md as the standard.

Some of this doc is dangerously dated. Some refers to TWs and TW writing conventions. Some tries to document functions, but dupes and diverges from places in the code where we clearly do that (JSDOC, etc). It's impossible to keep such documentation up to date and I suggest removing it. Make a local copy for personal use if you find it important to your flow.

Hopefully this MR awakens general interest in updating this material.

changed the description

added 1 commit

• ca306ce7 - code block type

Compare with previous version

The player and slave variable docs have been kept up to date, so I would appreciate them kept around.

We have PlayerState.js, no? Can you explain why we need both?

One's meant for documentation, the other definition. Just because someone slapped it all into the definition file does not mean it is suited for it.

You have to deal with commenting, making sure whatever notes you wrote down don't break actual code, etc. A text file can't break anything, which is why it is ideal for taking notes in.

Also formatting to an extent, as well as allowance for additional detail without flooding jsdoc? or whatever the editor that accesses those is.

I don't see the distinction. Documentation is right in the name, "JSDOC". I don't see you the text file as containing material that's too long for a tooltip, either.

If it's a key part of your own workflow, I'd suggest just making a local copy.

Regardless, I would prefer that it stayed, though moving to notes is fine.

Ok, brought them back. Placing them in the legacy area to encourage others to focus on the documentation.

Are the States at least linked anywhere or are people going to wandering around trying to find the documentation? That is most of the reason slave documentation was front and center. Bear in mind that it is crucially important for players to find easily due to how dependent custom rules are on the information contained in it.

If players are downloading the html, they will not get an md or txt and they also can't get into the state files.

If players are compiling themselves, they will have the state files.

Not sure how to encourage them to find any of it, but the md isn't better than the state files AFAIK. Perhaps a guide in the RA? We could give a hyperlink to the git I think.

No, I wouldn't put a guide in the RA, but in the encyclopedia segment about the RA, that might work out.

Ok, let me look into that.

edit: uh, @Pregmodder do we HAVE an encyc section for RA? The sidebar just links to the personal assistant from the RA, and that seems wrong.

edit2: ok, I think I found it.

We really, really should have one. It feels like it would a pretty big mistake to not have some sort of guide for one of the more complex management aspects of the game.

Was about to say, fcdev really would have dropped the ball not having something for it.

Yeah, the sidebar is wrong, I'll attach a fix for that too.

Let me know when everything is ready for merge.

@Pregmodder how's this look? Link will send them to the slave variable md on git itself.

A guide for the RA would be nice. If we are looking for an example set of rules with explanation of how they work, I wrote something about how my rules work a while back on reddit, here: https://old.reddit.com/r/freecitiesgame/comments/l4lb64/my_rules/gkrkfo7/

The user I was talking to said my rules and explanations opened his eyes on how the RA can be used, if it's useful for you, feel free to make use of it.

added 1 commit

• c3399afe - restored old variable doc

Compare with previous version

added 1 commit

• 0dec1625 - fix RA encyc link

Compare with previous version

merged

mentioned in commit 7daf11f9

mentioned in merge request !10190 (merged)