MediaWiki Documentation Day 2017
This page is obsolete. It is being retained for archival purposes. It may document extensions or features that are obsolete and/or no longer supported. Do not rely on the information here being up-to-date. |
The first annual MediaWiki Documentation Day will be held on Friday, May 12th. Help us prepare by listing high-priority documentation requests below and volunteering to address documentation requests that you are interested in tackling.
FAQ
editWhat is the scope of Documentation Day?
editDocumentation Day is intended to address documentation for any MediaWiki-related software, including APIs, extensions, services, libraries, gadgets, and bot frameworks. Target audiences for documentation include users, wiki administrators, and developers.
What does good documentation look like?
editGood documentation should have these seven properties:
- Clarity – easy to understand
- Coherence – easy to navigate
- Completeness – no missing information
- Concision – no extraneous information
- Consistency – uses the same terms and concepts throughout
- Correctness – tested and verified
- Credibility – Professional, no typos or grammar errors
For code documentation, please refer to the relevant sections of our coding conventions:
- Manual:Coding conventions#Documentation
- Manual:Coding conventions/PHP#Comments and documentation
- Manual:Coding conventions/JavaScript#Documentation
Am I required to participate?
editNo, anyone can contribute as much or as little documentation as they want, or abstain from Documentation Day entirely.
Requests
editPlease list any high-priority requests below. If possible, include the intended audience and any related Phabricator tasks.
Update on-wiki hooks documentation
editFrom Mainframe98: Update Manual:Hooks and create the missing hooks pages listed at Manual talk:Hooks and Category:Undocumented MediaWiki hooks. It's not a difficult task, since the hooks themselves are listed in hooks.txt in the MediaWiki source code. It's basically copy pasting with the occasional typo/format fixing. The version in which the hooks was added can be found by using git blame on hooks.txt.
- Phab tasks: task T157757
- Volunteers: Sam Wilson 01:19, 12 May 2017 (UTC)
Consolidate on-wiki Echo developer docs
editThere are currently 2 different pages of developer documentation for Echo (mainly about how to create new notifications). Some of the documentation overlaps and some of it is outdated. The docs should be updated and consolidated into one page if possible. Kaldari (talk) 18:34, 30 April 2017 (UTC)
- Existing docs: Notifications/Developer guide, Extension:Echo/Creating a new notification type
- Phab tasks: task T136372, task T162314
- Volunteers: ?
Improve ORES API documentation
editCurrently the ORES API documentation is a bit sparse and not great for getting new users up to speed. Stuff that could be added:
- Explanations of what sort of data is returned by the API and what it means. (Currently, it just assumes that you understand the scoring system.)
- Explanation of how to batch requests to the API
- Some example API calls and example responses
- Client code samples or links to existing client code that utilizes ORES
- Documentation of the new draftquality model
Interestingly, the meta talk page actually has lots of good documentation, but it isn't obvious to look there. (The weekly newsletters are also a good source of information.) Kaldari (talk) 02:07, 12 May 2017 (UTC)
- Volunteers: ?
Better documentation of MediaWiki database functions
editMost of the functions in Database.php have no code documentation. Let's add some. Kaldari (talk) 01:43, 12 May 2017 (UTC)
- That's because the doc comments were all moved to IDatabase.php. -- Tim Starling (talk) 05:53, 12 May 2017 (UTC)
- Should we maybe introduce the convention of using explicit @inheritdoc everywhere to make it clear to the reader that there is documentation elsewhere? --Tgr (WMF) (talk) 10:43, 12 May 2017 (UTC)
- That seems like a good idea. I don't imagine that many people ever look at IDatabase.php. I'll go ahead and add them to Database.php. Kaldari (talk) 16:47, 12 May 2017 (UTC)
- Done Added inheritdoc to most of the functions and wrote new documentation for the rest. Kaldari (talk) 01:15, 13 May 2017 (UTC)
- That seems like a good idea. I don't imagine that many people ever look at IDatabase.php. I'll go ahead and add them to Database.php. Kaldari (talk) 16:47, 12 May 2017 (UTC)
- Should we maybe introduce the convention of using explicit @inheritdoc everywhere to make it clear to the reader that there is documentation elsewhere? --Tgr (WMF) (talk) 10:43, 12 May 2017 (UTC)
- Volunteers: Kaldari
Results
editIf there are any results that you want to share, feel free to list them below.
- Template:MediaWikiHook#Finding_a_hook.27s_version_and_Gerrit_ID
- Manual:Hooks/AbortTalkPageEmailNotification
- Manual:Hooks/WatchedItemQueryServiceExtensions (needs more info)
- XTools user manual (need to decide if it's xTools, XTools, or Xtools...)
- Updated Continuous integration/Tutorials/Adding a MediaWiki extension
- Updated stuff about the mobileapps service and Android alpha builds here and on wikitech: wikitech:Mobileapps_(service), wikitech:Jenkins, Continuous_integration/Jenkins#Wikipedia_Android_alpha_app_builds
- Updated wikitech:Help:Tool_Labs/Web and wikitech:Help:Tool_Labs/Web/Lighttpd
- Made sure all functions in Database.php are documented (https://gerrit.wikimedia.org/r/#/c/353700/)
- Parsoid: Cleaned up DOM spec, Parsoid/Setup, Parsoid/Developer_Setup, Parsoid/Troubleshooting