Page MenuHomePhabricator

Organize a MediaWiki Documentation Day (similar to the Gerrit Cleanup Day) on 2017-05-12
Closed, ResolvedPublic

Description

On Friday, May 12th: https://www.mediawiki.org/wiki/MediaWiki_Documentation_Day_2017

It would be awesome if we devoted 1 entire day to doing nothing but documenting MediaWiki. There are countless classes and functions in MediaWiki core and its extensions that have no documentation. There is also a serious lack of high level documentation for developers. The problem is that documentation is often an after-thought and rarely gets focused attention from developers.

Some suggested projects that could be part of MediaWiki Documentation Day:

  • Tackle some of the blocking tasks at T2001 or Tracking-Neverending.
  • Add in-code function descriptions for important functions that don't have them.
  • Add in-code class descriptions to classes that don't have them.
  • Create documentation pages on MediaWiki.org for important classes in core that don't have them. See Manual:User.php for an example of a page that does exist. High-level documentation, like Manual:Title.php#Title_structure is especially useful.
  • Clean up our outdated documentation on MediaWiki.org.
  • Create README files for all the extensions that don't have them and make sure that all configuration variables are documented there.
  • Create some high-level documentation on how to write new API modules.

See Also:

Event Timeline

kaldari raised the priority of this task from to Needs Triage.
kaldari updated the task description. (Show Details)
kaldari subscribed.

Good idea. We need a driver, though. Any volunteers?

Framing this activity within something bigger makes sense. Good idea!

Would this task or any of the subtasks be a good candidate for Wikimania-Hackathon-2016? We are looking for tasks for newcomers / not very tech participants -- see T132721: Wikimania 2016 Hackathon Goals.

Maybe we could join this: http://www.writethedocs.org/conf/ to convince people

We are missing many conferences, but we can still focus on two:

  • Write The Docs Europe Unconference, July 19-20 2014, Berlin, Germany
  • Write The Docs Europe, Aug 31-Sep 1, 2015, Prague, Czech Republic

Any drivers willing to volunteer? The WMF might have some travel budget if there are volunteers with a track record on technical documentation interested in participating at these events.

We are missing many conferences, but we can still focus on two:

  • Write The Docs Europe Unconference, July 19-20 2014, Berlin, Germany
  • Write The Docs Europe, Aug 31-Sep 1, 2015, Prague, Czech Republic

Assuming wrong block picked to copypaste, so, the (ATM) actual is:

Write the Docs Europe, September 18-20, Prague, Czech Republic

Any drivers willing to volunteer? The WMF might have some travel budget if there are volunteers with a track record on technical documentation interested in participating at these events.

I'll check the conditions there and will decide then.

Removing Team Practices Group for now. Suggest you consider using a template along the lines of the example requests here:

https://www.mediawiki.org/wiki/Team_Practices_Group/How_To_Engage_With_TPG

Would this task be a good topic for the Wikimedia-Developer-Summit (2017) ? If so, the deadline to submit new proposals is next Monday, October 31: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/Call_for_participation

@Qgil I'd be very interested in a proposal around this, but honestly the nature and scope of the expected activities for the summit aren't clear from the CFP page. Maybe one or two generic examples, or ballpark estimates in terms of expected duration, level of structure, type (hands-on, discussion, presentation?...) would be useful. Or even some highlights among current proposals which could serve as inspiration.

This project is selected for the Developer-Wishlist voting round and will be added to a MediaWiki page very soon. To the subscribers, or proposer of this task: please help modify the task description: add a brief summary (10-12 lines) of the problem that this proposal raises, topics discussed in the comments, and a proposed solution (if there is any yet). Remember to add a header with a title "Description," to your content. Please do so before February 5th, 12:00 pm UTC.

Qgil triaged this task as Medium priority.Feb 20 2017, 8:58 AM
Qgil moved this task from Team radar to To triage on the Developer-Advocacy board.

This request ranked #15 in the Developer Wishlist Survey results. I am setting priority accordingly, and bringing the task under the scope (and not just the radar) of Developer-Advocacy.

Would anyone object if I pick this up and run with it? I'm thinking of scheduling it for Friday, May 12th. Does that conflict with anything important?

I don't think anyone would object any attempts to improve our docs, on the contrary. :)

@srishakatux, @Qgil: I've boldly created a page at https://www.mediawiki.org/wiki/MediaWiki_Documentation_Day_2017. Feel free to add to it or revise it completely. I'll send out an announcement to Wikitech-l and other venues this week. Let's not worry about making it perfect. We can just try it out on a small scale and see what happens. That's how Wikipedia started after all!

Got sign-off from Victoria and will be emailing out the announcement momentarily.

@kaldari Sounds great! Just wanted to add that there is a WriteTheDocs meetup happening this week on Thursday at WMF --
https://www.mediawiki.org/wiki/Write_the_Docs_San_Francisco_Meetup_May_2017. You're welcome to join and share what projects you're looking to get help on for documentation!

Thank you very much for organizing this!

https://www.mediawiki.org/wiki/MediaWiki_Documentation_Day_2017#Results exists (and looks good).

@kaldari: Anything else left to do here, or can this task be closed as resolved?

@kaldari: Anything else left to do here, or can this task be closed as resolved?

I take that silence as a "resolved".

Aklapper renamed this task from Organize a MediaWiki Documentation Day (similar to the Gerrit Cleanup Day) to Organize a MediaWiki Documentation Day (similar to the Gerrit Cleanup Day) on 2017-05-12.Jul 20 2017, 8:30 PM

Would be nice to repeat it from time to time, though.

Sure, Tgr, that can be done. Do you think it makes more sense as a remote effort, that's isolated from the rest of the tech events, or could it be something like a track at a physical event - would it be more effective?