Last modified: 2013-08-15 13:13:48 UTC

Wikimedia Bugzilla is closed!

Wikimedia has migrated from Bugzilla to Phabricator. Bug reports should be created and updated in Wikimedia Phabricator instead. Please create an account in Phabricator and add your Bugzilla email address to it.
Wikimedia Bugzilla is read-only. If you try to edit or create any bug report in Bugzilla you will be shown an intentional error message.
In order to access the Phabricator task corresponding to a Bugzilla report, just remove "static-" from its URL.
You could still run searches in Bugzilla or access your list of votes but bug reports will obviously not be up-to-date in Bugzilla.
Bug 50552 - README is unfocused & unwelcoming
README is unfocused & unwelcoming
Status: RESOLVED FIXED
Product: MediaWiki
Classification: Unclassified
Documentation (Other open bugs)
unspecified
All All
: Normal normal (vote)
: ---
Assigned To: Ori Livneh
https://github.com/wikimedia/mediawik...
:
Depends on:
Blocks: documentation
  Show dependency treegraph
 
Reported: 2013-07-02 04:50 UTC by Ori Livneh
Modified: 2013-08-15 13:13 UTC (History)
13 users (show)

See Also:
Web browser: ---
Mobile Platform: ---
Assignee Huggle Beta Tester: ---


Attachments

Description Ori Livneh 2013-07-02 04:50:34 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.
Comment 1 MZMcBride 2013-07-02 13:35:20 UTC
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.
Comment 2 Quim Gil 2013-07-03 15:35:22 UTC
... and that wiki page could be https://www.mediawiki.org/wiki/Manual:What_is_MediaWiki%3F
Comment 3 Ori Livneh 2013-07-27 01:52:21 UTC
(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 ?
Comment 4 MZMcBride 2013-07-27 01:53:38 UTC
(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. :-)
Comment 5 Ori Livneh 2013-07-27 02:08:33 UTC
(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.
Comment 6 Gerrit Notification Bot 2013-07-29 22:37:38 UTC
Change 76643 had a related patch set uploaded by Ori.livneh:
Update README w/changes from MediaWiki.org

https://gerrit.wikimedia.org/r/76643
Comment 7 Gerrit Notification Bot 2013-08-02 18:06:14 UTC
Change 76643 merged by jenkins-bot:
Update README & COPYING

https://gerrit.wikimedia.org/r/76643
Comment 8 Quim Gil 2013-08-15 13:04:59 UTC
Ori's patch has been reviewed and merged. This looks FIXED now. Thank you!
Comment 9 MZMcBride 2013-08-15 13:13:48 UTC
(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. :-)

Note You need to log in before you can comment on or make changes to this bug.


Navigation
Links