https://bugzilla.wikimedia.org/show_bug.cgi?id=50552
Web browser: ---
Bug ID: 50552
Summary: README is unfocused & unwelcoming
Product: MediaWiki
Version: unspecified
Hardware: All
OS: All
Status: NEW
Severity: normal
Priority: Unprioritized
Component: Documentation
Assignee: [email protected]
Reporter: [email protected]
Classification: Unclassified
Mobile Platform: ---
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.
--
You are receiving this mail because:
You are the assignee for the bug.
You are on the CC list for the bug.
_______________________________________________
Wikibugs-l mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/wikibugs-l
