This doc, https://wikitech.wikimedia.org/wiki/Help:Toolforge/Database, is an important page with too much information in one place. It includes how-to instructions for accessing wiki replicas via Toolforge, conceptual content about database structure, and code examples.
Main issues with this doc:
- It's confusing that this page combines info about accessing the wiki replicas databases as well as user-created "toolsdb" databases.
- It's too long! It combines how-to steps and reference information about database schema. Information about database layout also exists in https://wikitech.wikimedia.org/wiki/Help:MySQL_queries.
- The language-specific code examples section contains some examples of connecting to toolsdb host, and some examples of connecting to the hosting cluster for replica dbs; it would be better to have examples for each host in each language, or only include examples in the sections for wiki replicas or toolsdb instead of in a big list at the end. Even though it's relatively simple to change the host address if you're copying and pasting, this just adds to the confusion on this page.
- Examples of how to connect are also on https://wikitech.wikimedia.org/wiki/Help:MySQL_queries. These types of examples should be consolidated in one place and then cross-linked rather than duplicated.
- Check all code examples to verify they're still correct and runnable.
To fix this issue, I suggest breaking the Help:Toolforge/Databases page into separate pages for:
- How to create, connect to, and query tool databases (repurpose this existing page)
- What are the wiki replica databases, how are they organized, including layout and available/redacted tables. (repurpose this page) | (move in some content from https://wikitech.wikimedia.org/wiki/Help:MySQL_queries)
- How to access and query the wiki replica databases; connection example code and sample queries; things to be aware of when writing/running queries. (move all of this how-to type content out of aforementioned docs and in to https://wikitech.wikimedia.org/wiki/Help:MySQL_queries; give the page a more accurate name).
Additional suggestions for specific improvements may be noted in the thread below.