It would be nice to have an area that explains OGS features, like game scoring, ranking, etc.
An example: I am currently following a thread where people are arguing about the impact of timeout on ranking. The “funny” part of this heated discussion is that there is no reference that clearly explains how the ranking system currently counts timeouts.
Another common rant is about incorrect group status when scoring, in particular in correspondence games. Here too I believe that a minimum of documentation would help clear some misunderstanding.
The first correspondence timeout counts towards your rating. After this, the player is tagged with a “recently timed out” marker and all subsequent correspondence timeouts are annulled until the player wins their first correspondence game that has lasted longer than 24 hours (note that this game didn’t need to start after the timeout, only the total time is relevant). After this, the “recently time out” marker is removed and the player can once again lose rating points through means of a timeout.
Anyone can gain rating points at any time from a correspondence timeout win, as long as both players have played at least 1 move and the loser is not already branded with a “recently timed out marker”
I think that very few people would argue that there should not be such documentation.
The real problem, faced by every application in existence, is “who is going to write it and curate the documentation?”
Generally speaking, developers of open source/community apps prefer to spend their time writing features and fixing bugs to writing documentation. But they are really the only people who can authoritatively say what the application does.
It’s not impossible to have community developed and curated content of this nature.
Knowledge about how things work can be captured from posts from the developers, just like BHyden did up there, and put in one place.
Do you have a proposal for how and where this should be done, and by whom?
It’s kind of outdated though the basics are there, but if anyone feels up to the task there is a suggest edits button. But maybe discuss with mods prior to devoting a lot of time into it
@GreenAsJade I hear you, but I find zero documentation a bit extreme.
Also, in my experience, devs who offer minimal documentation compensate by closely monitoring and participating in forum discussions. It doesn’t seem to be the case here (cf. above example).
So if my assumption is correct that there is currently no documentation, and if the core team doesn’t plan to be involved in the discussions related to feature implementation, I think starting with a FAQ would be a nice and lightweight choice.
Thanks! Now I remember visiting those pages, but I don’t recall how I landed there. I don’t see any link from the OGS home.
This is very high level documentation, I don’t even see anything about scoring.
[Edit] My search on scoring didn’t return any result, but there’s actually a “stone removal” section. I am still wondering how this works in correspondence games (after the second player passes, how much time does the first player have to reconnect and score the game?)
I could have included in my list the score estimate bug thread. The topic just came back once again today.
Another common one is: “I just won a game, how come my ranking didn’t change (or went down)”.
To answer my initial question, a documentation already exists (thanks @Adam3141) and just needs higher visibility. What is still needed to declutter the forums is an FAQ that covers half a dozen common topics.
Sounds like a great idea. Having a pinned FAQ at the top :D. @trohde or any other mods? (sorry Tom, there is no universal mod shoutout and you just come to mind first ) Totally willing to to write some mock up if deemed worthy.
But on the other hand, if there was no mystery what would we do here at the forums?
Thanks for thinking of me, @Adam3141, but I’ve been quite comatose as an admin, and I can’t see that it will change in the near future.
BUT what about just creating that mock-up as a PM here to me and a few other (preferable more active) mods and maybe also other active and interested users (which also can be invited later), and there we can discuss and change it, etc., and then when we’re happy with it we could make it a post that could be pinned?
Just an idea to have it somewhat polished before making it a post that’s visible to everybody.
I’ve written several posts on this subject—including my first created topic, regarding the inadequate explanation of the stone removal phase. I have also pointed out the obscure location of the existing documentation. So I very much agree with you (@SanDiego)! Generally my posts received little response, so congratulations on sparking some discussion.
I believe that an FAQ is important enough to have it listed under the OGS logo, if not as a tab on the top line. A way to start would be to compile a list of subjects or questions that need explanation. This might be done by scanning the forum topics.
Oddly, my preceding reply was made directly to SanDiego, using the proper reply button, yet it was not listed as a reply to SanDiego, so I had to add an edit identifying him in the parenthetical.
Who wrote the https://ogs.readme.io/ help entries? Even if they are incomplete, the docs were very helpful for me, and I believe others would find them useful as well. Linking to documentation from the top level or hamburger menu, as suggested above, is a good idea!
Well imho they should be rewritten first. these are still for the old version with old screenshots and functions. And while a big part is still relevant it might get very confusing for many members…
) Totally willing to to write some mock up if deemed worthy.
