Page MenuHomePhabricator

README is unfocused & unwelcoming
Closed, ResolvedPublic

Description

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

Details

Reference
bz50552

Event Timeline

bzimport raised the priority of this task from to Medium.Nov 22 2014, 2:00 AM
bzimport set Reference to bz50552.
ori created this task.Jul 2 2013, 4:50 AM

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.

ori added a comment.Jul 27 2013, 1:52 AM

(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. :-)

ori added a comment.Jul 27 2013, 2:08 AM

(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

Qgil added a comment.Aug 15 2013, 1:04 PM

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. :-)