How to organize documentation - user guides on website?

[DanVanAtta]

Proposal

Inspired by the eslint.org, suggestion is to add new 'guide' pages to website: https://triplea-game.org/

For us the proposed guide pages would be:

• Player Guide
  • Lobby Rules
  • How to Host
  • FAQ (?)
• Map Maker Guide
  • How to Make Maps
• Developer Guide
  • Getting Started

For Discussion / TBD

This proposal would move documentation to the website. We previously had documentation on website and moved it back to the code. We need to decide if we will be ping-ponging between documentation locations. My thinking is we move all generic non-project and non-design documentation to website. That helps keep the code base documentation cleaner for concepts specific to that code base.

I suspect adding 'player' and 'map maker' guides will be a win so we can make the website more useful and to make that content easier to find.

[RoiEXLab]

@DanVanAtta There's currently a lot of documentation on the forum. The key benefit I see there is that it has a low cost of keeping everything up to date. The moderators can easily update posts even on their phones and if there's a problem with it users can quickly post their questions below the post. On the other hand I agree that having a website makes finding those posts easier.

[DanVanAtta]

Late replying, the problem I've seen with forum posts is that it usually is, despite our best intentions, only the original poster that keeps the first post up to date. Even when updating something out of date, I feel it is ackward to update a post someone else has posted.

Regardless, we need to be sure that documentation is accessible. The most salient problem we have is scattered and duplicated documentation. After having collected the documentation a few times, it was pretty common to see the same thing documented multiple times.

I suppose this raises a broader question of how do also account for documentation that is in the forums.

[DanVanAtta]

Given our history of documentation, I don't think we'll ever quite hit the level of clean, non-duplicated documentation on the forums as we would a website location that is checked in and clearly something we would all maintain.

IMO forums probably should be a supplement to user guides, the guides on the website on the other hand serving as a central place for documentation that is consolidated and kept up to date.

With that said, this seems like a project ticket rather than a simple task.

@ron-murhammer @prastle, have you had time to review this issue, does it seem like a correct direction?

My thinking is the forums would then be more dedicated to pinned topics that would link to guides that are the documentation, and otherwise the forums would be more for live conversations and not for documentation.

[ron-murhammer]

@DanVanAtta I'm fine with that direction. I don't care much where we keep/host the docs just that they are maintained and that we minimize duplication.

[DanVanAtta]

Thanks for feedback @ron-murhammer

Closing, this PR: https://github.com/triplea-game/triplea-game.github.io/pull/316 gets a start on this task.

[DanVanAtta]

/cc @prastle once we get a bit further along with the user-guide posted to website with rules and how-to info, I think we can then prune the content on forums. It'll also be really good then to spend some time updating links/references to direct users to the user-guide for things like lobby rules