MediaWiki Documentation Day 2017

From mediawiki.org

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[edit]

What is the scope of Documentation Day?[edit]

Documentation 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?[edit]

Good 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:

Am I required to participate?[edit]

No, anyone can contribute as much or as little documentation as they want, or abstain from Documentation Day entirely.

Requests[edit]

Please list any high-priority requests below. If possible, include the intended audience and any related Phabricator tasks.

Update on-wiki hooks documentation[edit]

From 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.

Consolidate on-wiki Echo developer docs[edit]

There 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)[reply]

Improve ORES API documentation[edit]

Currently 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)[reply]

  • Volunteers: ?

Better documentation of MediaWiki database functions[edit]

Most of the functions in Database.php have no code documentation. Let's add some. Kaldari (talk) 01:43, 12 May 2017 (UTC)[reply]

That's because the doc comments were all moved to IDatabase.php. -- Tim Starling (talk) 05:53, 12 May 2017 (UTC)[reply]
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)[reply]
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)[reply]
Yes Done Added inheritdoc to most of the functions and wrote new documentation for the rest. Kaldari (talk) 01:15, 13 May 2017 (UTC)[reply]
  • Volunteers: Kaldari

Results[edit]

If there are any results that you want to share, feel free to list them below.

Retrieved from "https://www.mediawiki.org/w/index.php?title=MediaWiki_Documentation_Day_2017&oldid=5026832"