GitHub's practice of extracting and rendering the README below the repository file browser means the README file gets a lot more exposure than it used to. It is increasingly the first bit of MediaWiki documentation that developers encounter, and it is awful.
Problems:
- Out of date, incomplete.
- Describes MediaWiki in tepid or downright negative terms.
- No clear value proposition.
- Declines to give clear advice.
- Lacks clear scope.
- Duplicates CREDITS.
- Too damn long.
The README should start out by telling you what MediaWiki is and why you might want to use it. It should then highlight some stand-out features that set it apart from other platforms in its category.
An outline of the installation procedure should follow, and it should be idealized rather than thorough. Readers will know to turn to INSTALL or UPGRADE or MediaWiki.org for in-depth coverage. For now the purpose is merely to convince the reader that installing MediaWiki is simple and straightforward.
Links to additional resources should be aggressively pruned. It is important to remember that the README is not a master document but an entry-point. A single link to MediaWiki.org should suffice. We should underscore the vitality of our developer community by mentioning some of the places where we interact and by actively encouraging people to participate and contribute.
Version: unspecified
Severity: normal
URL: https://github.com/wikimedia/mediawiki-core/#readme