Last modified: 2013-08-15 13:13:48 UTC
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.
I'll add "duplicates LICENSE" as a potential problem as well. One idea was to put the contents on a wiki page and have a three-month period where users can edit and update the README's contents. This might foster more collaboration and discussion.
... and that wiki page could be https://www.mediawiki.org/wiki/Manual:What_is_MediaWiki%3F
(In reply to comment #1) > One idea was to put the contents on a wiki page and have a three-month period > where users can edit and update the README's contents. This might foster more > collaboration and discussion. I think it's a really good idea, but I don't see the benefit in waiting three months to merge the changes into mediawiki/core. We should simply agree to merge changes from the wiki page to the repository on an ongoing basis. (In reply to comment #2) > ... and that wiki page could be > https://www.mediawiki.org/wiki/Manual:What_is_MediaWiki%3F I think it's a good page and we could probably take some of its content and adapt it for the README, but I don't think they're identical in scope. For one, the page is concerned with disambiguating the concept of MediaWiki from Wikipedia, whereas readers of the README are presumably not confused, by dint of encountering the file as part of the source code distribution. So I think it should be a separate page. How about https://www.mediawiki.org/wiki/README ?
(In reply to comment #3) > So I think it should be a separate page. How about > https://www.mediawiki.org/wiki/README ? Sounds good to me. Please start the page. :-)
(In reply to comment #4) > (In reply to comment #3) > > So I think it should be a separate page. How about > > https://www.mediawiki.org/wiki/README ? > > Sounds good to me. Please start the page. :-) Cool. Started.
Change 76643 had a related patch set uploaded by Ori.livneh: Update README w/changes from MediaWiki.org https://gerrit.wikimedia.org/r/76643
Change 76643 merged by jenkins-bot: Update README & COPYING https://gerrit.wikimedia.org/r/76643
Ori's patch has been reviewed and merged. This looks FIXED now. Thank you!
(In reply to comment #8) > Ori's patch has been reviewed and merged. This looks FIXED now. Thank you! Indeed. Thank you for marking it as such. Anyone and everyone should feel free to continue editing [[mw:README]]. It should be occasionally re-synced with the distribution file, but if nobody notices for a while, please open a new bug report requesting a re-sync. :-)
