I’ve been evangelically introducing new users to OGS lately (sorry if they haven’t been the best to play with) and in trying to help them learn how to use the site I’ve been linking them to the readme file here: https://ogs.readme.io
I think having a readme file is massively helpful, however, this one is getting a bit out of date. I’ve emailed @anoek and they said they are game for updating it. Another option is moving things to Github Wiki making Github the one shop stop for info people might be seeking.
The developers have a lot on their plates I’m sure, so I’m not trying to burden them with more work. In fact, I’d love to help update the wiki/readme! But I just wanted to post this and see how people feel about having a central document that explains the details about how OGS works.
(Note: OGS is grandfathered in to a free subscription fee with readme.io, so no worries about lost funds there)
Lol, exactly! I’ve never seen anyone post on the forum about it, but it’s a terrific resource that explains how OGS works in decent detail (plenty of stuff I’d add), but many of the new features and way things work are missing from the current one.
Ok. Serious this time. I know about readme file from the time I started tinkering with OGS API. But whenever someone brings it up, I can’t help but write something like “we have a readme file?” because I doubt many people actually read it.
First problem with readme is that you can’t intuitively find it from OGS home page. Or at least I can’t. Maybe it makes sense if it’s outdated, but if we want to bring it back, we have to link it at obvious place.
Second problem is that it’s kind of a wall of text. It’s boring to read.
Third problem is that you don’t need readme to play, so a lot of players just don’t read it and miss out on some nice features.
It doesn’t look like a wall of text to me. The writing is quite heavily interspersed with images, and furthermore has been split into small paragraphs.
The idea of updating the file was previously discussed here: Documentation or FAQ. The problem seems to be that there is no one to organize and oversee the effort.
The obscure location of the file would greatly undermine the value of even a brilliant, up-to-date text. Also, I think it needs to be on OGS, not on some other site.
Linking to the file could be part of a “welcome to new players” message if it isn’t already.
Nonono, not so, if there are willing hands I think we could do it. I said so several times, but guess never visibly enough I will make sure that there are not any plans to any major changes of the location or platform as not to waste potential hard work and then, any volutneers are welcome, we will divide the work equally
Okay, I’m willing to help with some writing/editing. Of course, someone, or several people, should review all the work to make sure everything is accurate. The first question that comes to mind is the mechanics of the task. Is it to be done wiki-style among a group of volunteers, or do we copy and paste text into a Word file and then go to work? Or…?
I’d be willing to help with anything here as well - not sure how much use I’d be, but I can at least be a set of editing eyes at some point if that’s what’s wanted somewhere along the line.
My point is that it’s written like a manual. I don’t want to read all that.
I’d rather have a FAQ-like structure so if I need to learn how to search for a user, I can find just that. At the moment it’s unclear to me where in the readme I can just learn about user searching and if it’s written there at all.
By the way, try out “Search” field in upper-right. Quite unfriendly search bar.
I can possibly translate stuff to Russian, if needed.
First of, thank you all for the kind offers , you are awesome.
Give us a day or two (or three), to try and sketch-up some plan. It seems that we will be moving away from the readme.io platform. So at the moment I am unsure about the wiki-mechanics, it might just be easiest to create some shared google doc so we can all start working, but let me get back to you on that as well.
Then perhaps the thing to do would be not to chuck away the readme file but to add two parts to the start: firstly, a video that explains a lot of what’s written there along with a person actually finding and doing the things on their screen; and secondly an FAQ page.
You know what the most common question I’ve had to field in the OGS chat has been, by far? “Where is [X feature]?” that is in the menu, after which they also need to be pointed to the menu as it’s not visible any more (which I do think is good from a design point of view for regular users.)
This could be fixed with a small bit of text saying something like:
“Many features on OGS are accessible from the menu. The menu can be opened by clicking on the logo in the top left of the screen, which looks like three horizontal lines. Features available from the menu are X, Y, Z…”
I think it’s all setup, and I’ve opened up edit access, I think folks just need a github account to contribute (which are free).
I haven’t put anything up there other than a stub index page to get things setup. I have no attachment to the format or any content on the ogs.readme.io site, so if folks are passionate about getting the documentation updated, feel free to use or not use anything from there.
Thanks for the interest in this, it’d be great to have that updated for folks!
Let me know if y’all need anything else from me in terms of setup stuff on the github wiki or anything else.
Okay, let’s try to get this done. First things frist I have tried to sketch up some outline (mostly copied from the existing one), but I am sure you all have your own experience with what you looked for when you were starting, so please critique, expand. Let’s keep it public for a little while more - maybe someone else will join in on the fun - and then when we actually start typing I guess we will switch to private converstaion as not to spam too much.
Getting started (setting up an account)
signing in
adjust everything to your preference
check the rules
your new rating
basic screens explained
short ToS?
Finding a game
auto match / custom match
find/challange a friend
play with a bot
quick time settings explanation?
Actually Playing a game (mostly copy)
making moves
chatting
passing
resign vs cancel
undo
pause
analyze
…
score
Reviews and demos
review an existing game
create a demo
uploading an sgf
Ladders, tournaments, leaderboards
Getting involved in the community
chat
groups
forums
FAQ Ettiquette? Troubleshooting
Feel free to call dibs on which one you would be interested working on. @Spiffers if you are not comfortable actually writing any of it a grammar check after all is done would be much appreciated as well
Under ‘Actually Playing a Game’ I would include: Scoring a Game. It’s easy to think that the auto-score is some kind of referee if you are new to the site and new to Go. It needs to be made clear that auto-score is just a starting point for agreeing the score and that a continuation is possible to resolve the score.
oh, yeah forgot to add that. Well I am afraid neither of us has the knowledge, so we will not be working on the API part, I assume only anoek can do that if he finds the time. Maybe we can start bugging him about it once we get the basic readme running.
describe all the stuff on the overview and profile page.
we have to describe what rank/rating are.
maybe some words to the leaderboard??? New players ask sometimes how the scores get calculated.
puzzles
how to become a supporter
PS: I can help a little with some API stuff if I find time. I don’t know everything of the API and nothing of the real time API, but I use the /api/v1 and /termination-api regularly.
I will make sure that there are not any plans to any major changes of the location or platform as not to waste potential hard work and then, any volutneers are welcome, we will divide the work equally 
, you are awesome.