@awight I've been thinking about what will appear at https://mediawiki.org/wiki/ORES. Why would we put anything there rather than just having it in the README.md at https://github.com/wiki-ai/ores?

I'm sure that would be fine. The wiki page would potentially enable translation, but that's not a problem we have at this point.

Subpages and embedded images in the readme will probably have to live in a docs/ directory, and I'm not sure what Markdown support looks like. Seems to be a sort of clumsy notation that requires the image to be hosted somewhere, c.f. http://stackoverflow.com/questions/14494747/add-images-to-readme-md-on-github

I'd also ask, what are the advantages of documenting in the readme file? Self-containedness, for one. I'm not sure which is going to enable wider collaboration, or be more accessible.

I wonder if we could do a good mixture.

So, we have:

• https://mediawiki.org/wiki/ORES (Long-form discussion of architectural strategy with diagrams)
• https://github.com/wiki-ai/ores (Basic installation and operation with link to mw:ORES)
• https://pythonhosted.org/ores (TODO: Auto-generated low-level API docs)

I just extended https://etherpad.wikimedia.org/p/ORES_docs_split to include these two additional documentation spaces.

We can use .wiki files in github. Let me grab an example

https://github.com/wmde/WikibaseDataModel/blob/master/docs/foreign-entity-ids.wiki

@Ladsgroup and I were looking at the etherpad and we realized that mediawiki.org is in a weird spot because the extension/beta feature directs users to the MediaWiki.org pages. But our general user-facing documentation is on Meta. @awight, I'm wondering what you think about this problem. Should we move our user-facing documentation from Meta?

@Eugene233 feel free to use this task instead of T174858 for a guide of updating docs