Page MenuHomePhabricator

MediaWiki Documentation
Closed, DeclinedPublic

Subscribers
Tokens
"Like" token, awarded by Tgr."Yellow Medal" token, awarded by Seb35."Like" token, awarded by Krenair."Like" token, awarded by Miriya52."Love" token, awarded by Samwilson."Party Time" token, awarded by bd808."Love" token, awarded by demon."Like" token, awarded by Aklapper."Like" token, awarded by Trizek-WMF."Like" token, awarded by Bawolff."Like" token, awarded by MusikAnimal."Love" token, awarded by Jan_Dittrich."Love" token, awarded by waldyrious.
Assigned To
Authored By
kaldari, Oct 27 2016

Description

Session title

MediaWiki Documentation

Main topic

How to grow our technical community

Type of activity

Unconference session

Description



=== 1. The problem ===
Lack of good technical documentation is a huge impediment to growing our technical community. We need to improve both our high-level documentation on MediaWiki.org and our low-level documentation within the code itself. We also need to update and improve our existing documentation. Better docs will help new developers quickly get their bearings and figure out how to make useful contributions.

=== 2. Expected outcome ===
Brief discussion of documentation pain points and best practices, followed by a work session to actually write documentation! Possible tasks include:
* 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 [[ https://www.mediawiki.org/wiki/Manual:User.php | Manual:User.php ]] for an example of a page that does exist. High-level documentation, like [[ https://www.mediawiki.org/wiki/Manual:Title.php#Title_structure | Manual:Title.php#Title_structure ]] is especially useful.
* Clean up our [[ https://www.mediawiki.org/wiki/Category:Outdated_pages | 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.

=== 3. Current status of the discussion ===
{T2001}

=== 4. Links ===
* https://www.mediawiki.org/wiki/Manual:Contents
* https://www.mediawiki.org/wiki/Manual:Coding_conventions#Documentation
* https://doc.wikimedia.org/
* http://www.writethedocs.org/guide/

== Proposed by ==
@kaldari

== Preferred group size ==
?

== Any supplies that you would need to run the session ==
?

== Interested attendees (sign up below) ==

# @Qgil
# Trizek-WMF
# @Tgr
# @MusikAnimal
# @Xephyr826
# Add your name here

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
Jan_Dittrich added a subscriber: Jan_Dittrich.EditedNov 1 2016, 12:44 PM

@waldyrious : Yes, standards would make a lot of sense, +1.

@Tgr: Good points. For the developers who don't write docs, I have no great solution (I would see writing docs as similarly to writing test); However, if people are willing to write them, but have a hard time to make it easy to understand, there may be some infos and methods that help, like:

  • Use your docs if new team members, interns etc. are onboarded. Note where they have problems and what their questions were.
  • Highlight that problems with the docs can be reported on the talkpage/phabricator/etc. (also link to the documentation for those functions)

Some basic principles I try to follow:

  • We can not assume that the purpose of a piece of code will be obvious without any explanation
  • Anything we assume to be "Basic knowledge" should at least have a link. For example the wikibase documentation does not mention that Mediawiki is needed to use it. We can also not assume that it is clear for everyone what "composer" is or "vagrant" or… Yes, it is not our task to explain it. But it is to direct people to places where they can get these explanations.
  • Examples or tutorials are essential for onboarding newcomers. A code level documentation is great and important for experienced developers, but it is hard to learn how to contribute to the software just from it – Just as it is hard to learn solving mathematical problems if you are only provided a set of formulas and axioms.

Just an idea the WritetheDocs Event this year was a 5 days event with one Hacking Docs Day where everyone was able to work on the docs he wanted. Could we not use their infrastructure to work on our documentation as one event ?

Another pain point is that as soon as MediaWiki documentation pages are marked up with translate tags, no one wants to edit them any more (as I've heard from multiple developers).

@samuwmde: I ping @gabriel-wmde, he was at the Writethedocs event and might know more.

Qgil added a comment.Nov 9 2016, 3:25 PM

@kaldari , just to be clear, are you willing to drive this session? If so, please assign the task to yourself.

kaldari added a comment.EditedNov 9 2016, 8:55 PM

@Qgil: That depends on when it is scheduled and if it conflicts with Community Wishlist sessions. If anyone else is interested in driving it, I would be happy to let them.

Qgil added a comment.Nov 10 2016, 10:51 AM

Actually it goes the other way around: if you want to drive this activity and you are also involved in the pre-scheduled sessions of the Community Wishlist, then the Program committee (where you are involved) will just avoid the clash. Meaning: you will be involved in the creation of the schedule, so no worries. :)

Qgil assigned this task to kaldari.Nov 11 2016, 12:15 PM

(I'm taking the liberty)

MusikAnimal added a subscriber: MusikAnimal.
Trizek-WMF added a subscriber: Trizek-WMF.

Is "MediaWiki documentation" the right scope, though? Personally, and for the sake of growing our technical community, I am especially interested in the documentation that newcomers will need to get up to speed. If this part is solved, then dealing with the wider mess is easier. If this part is not solved, then newcomers will not even reach the point to need the "deeper" documentation.

For this reason, I would suggest to focus on Documentation for newcomers.

If we agree on this, then the question is what is the documentation for newcomers. We have what I think is a big problem: while at a "social" level we have agreed that contributing to MediaWiki core or writing a new extension are not the best first steps for a newcomer, at the documentation and support level we keep pointing to MediaWiki core and new extension development prominently.

What if the trick for growing our technical community indeed would be to put the emphasis on e.g. Wikimedia APIs & Labs, contributing to Android & iOS apps, developing Gadgets and Templates? Documentation to contribute to extensions would make sense too, but focusing on a curated list of projects actively welcoming code contributions. The Community Wishlist could also serve as a guideline for the type of documentation needed by potential volunteers willing to work on wishes.

I don't think we should be the ones to choose where to put the emphasis. It could well be that newcomers to Wikimedia development would be interested in working on high-impact issues (the same reason why editing articles on Wikipedia and having the result immediately published for all to see is attractive), which may include submitting changes to core MediaWiki. Are there any processes through which we could collect what documentation resources people are lacking the most? Maybe the Analytics team has collected / can collect some data in that regard?

Tgr added a comment.Nov 22 2016, 9:17 PM

"newcomers" as in people relatively new to programming? That's a reasonable hypothesis but it would be nice to see some data behind it. (In general it would be nice to see data. I don't think we ever did any surveying of what is the average experience level of our community, what is the experience level of people who have recently joined, what reasons they joined for etc.)

If you mean it more generally, then I am not sure it narrows documentation issues much. E.g. if someone gets involved in the community because they just inherited a MediaWiki instance they have to maintain, they probably need good documentation of hooks/config vars and some overview of those two systems. If someone is looking for a platform for a new knowledge curation community, they need a better maintained version of MediaWiki feature list. For a Wikipedia editor who is becoming a technical contributor, we probably need documentation about gadgets and Wikimedia Labs. Etc.

@Qgil I assume that starting with scripts and APIs makes sense for the most users. Though in my impression, the lack of examples and overview/"entry information" seems to be fairly common in many fields.
@waldyrious: Search queries might be interesting for this.

@Tgr: Julia and @samuwmde did qualitative research with volunteers who contribute to our code.

It seems that we might want to research and define some user groups or personas in order to focus our efforts.

demon awarded a token.Nov 23 2016, 9:07 PM

Create README files for all the extensions that don't have them and make sure that all configuration variables are documented there.

I actually don't think that's all that useful. I think its much better to document on the Extension: page at mw.org, and make that the canonical source for config directives. In my experiance the README files tend to get out of sync much faster than the mw.org doc.

Samwilson rescinded a token.
Samwilson awarded a token.
Seb35 awarded a token.Nov 28 2016, 8:02 AM
Seb35 added a subscriber: Seb35.
samuwmde added a subscriber: QuimGil.EditedNov 28 2016, 9:03 AM

We did qualitative Interviews with Media Wiki Volunteer Developers to get to know what their better. Backround is that we did some acitivities for Volunteer Developer @Wikimedia Deutschland (e.g. Hackathons, Scholarships, Outreach) the last 2 years. In this Interviews through a series of open ended questions volunteers were asked about three themes, history/motivation to volunteer and program, cooperation with Wikimedia Germany and the volunteers, information & communication in the projects and Wikimedia Deutschland’s role in the open source movement. The interviews were structured to the extent that the interviewer had questions prepared, however participants could take the conversation in directions they found relevant. Participants agreed that their answers can be published anonymously. Some first findings we got out it are:

  • volunteer developer started with 20 hours per week
  • all interviewees named specific people who they engaged with during their volunteering time and this is what led to the start of new features and project contributions
  • like to have the freedom to choose tasks
  • offline communication is very important for their work
  • to know staff in person their work together with is important for their work

    So we planned to share all the results on the Developer Summit but I didn't hand in a session because I thought the topic is too non-technical for the summit. @QuimGil Are there similar findings out of the big quantitative community engagement survey?
Qgil removed a subscriber: QuimGil.Nov 30 2016, 9:24 AM

@samuwmde I would like to reply to your post, but this is a Summit proposal about "MediaWiki documentation", and I fear we would be deviating too far away from the topic. Let's continue at T131689: Second iteration of the Technical Collaboration strategy for now?

The reason why I was jumping in, was to bring up some ideas how to tackle it. A big finding of the develop interview was that it's really hard to find important documentation because you don't know really where to find the right information and for this you need someone who helps. Staff member or experiences developer. Some documentation is also not up to date.

One example what we did this year to tackle the problem was:

@johl and @gabriel-wmde had a workshop at the Writing Day @ WritingtheDocs to write the Intro for our Query Service for people who have non technical background. So Jens did a short presentation around Wikidata to catch new people who liked to work on. In the group of ten (wikimedia people and non wikimedia people) their, tackled the questions:

  1. What is the target group? Are we writing for developer or non-developer? Are there having a technical background or not?
  2. What could be interesting for this target group? (Brainstorming)

After this their Brainstorming, their structure little working packages, people were able to work on independently during the day. As result, we got a really good new documentation. Overall when you have someone like Jens who is passionate about the product, a great communicator and focussed on the user need to hold the workshop it's motivating, you can catch new and experienced people to work on documentation.

I can imagine when we prioritizing documentation needs in the movement, choose personas (@Jan_Dittrich has great methodical skills around this) to identify the target group for documentation and design single workshops which focussing on one issue per event e.g. DevSummit, Hackathon, WritetheDocs this could be a great ongoing documentation workflow.

Qgil added a comment.Dec 2 2016, 9:00 AM

In terms of room capacity and configuration, what would be your preference?

  • The biggest room in theater configuration (up to 200 people, only chairs, no tables) and required video recording (meaning also that people have to wait for the mic to speak etc).
  • A big room in classroom configuration (up to 70-80 people, chairs and tables) and required video recording (meaning also that people have to wait for the mic to speak etc).
  • A big room in classroom configuration (up to 70-80 people, chairs and tables) and optional video recording (i.e. only recording the initial introduction but then relaxing things during the discussion, or no recording at all).
  • A smaller room, flexible configuration, optional video recording...

Probably a smaller room as I doubt there will be a huge audience for this.

This is a topic I'm very interested in as a technical writer and new MediaWiki contributor.

One idea I'd like to propose is an effort to connecting the technical writing community and the MediaWiki community.

San Francisco and many other places have a strong Write the Docs community. Within this community, I am sure there is an untapped resource of people with an interest in contributing to open source projects and with a passion for writing great documentation.

At Write the docs in Prague we had a big room for the introduction of the projects (for us that could be the introduction of different areas where documentation is needed) and working at tables (both in the big room and in smaller rooms) after the introductions were made. I think that worked very well: Everbody got an overview of what to work on and then every group had their space.

johl added a comment.Dec 7 2016, 3:04 PM

+1 to what @gabriel-wmde says. I would love to see technical writing handled in the same way as working on software, with an introduction in front of everyone to get potential contributors and then a table/small room to work on the project. I would also be interested in helping to organize this for the Hackathon in Vienna (and possibly the Wikimania Hackathon).

Qgil added a comment.Dec 8 2016, 10:25 AM

You gave me a somewhat related idea. At the opening of the Summit, we could give a chance to Unconference session promoters to pitch their session very briefly (as in 20 seconds) T147955#2856759. I just wanted to say Thank You. :)

@kaldari Hey! As developer summit is less than four weeks from now, we are working on a plan to incorporate the ‘unconference sessions’ that have been proposed so far and would be generated on the spot. Thus, could you confirm if you plan to facilitate this session at the summit? Also, if your answer is 'YES,' I would like to encourage you to update/ arrange the task description fields to appear in the following format:

Session title
Main topic
Type of activity
Description Move ‘The Problem,' ‘Expected Outcome,' ‘Current status of the discussion’ and ‘Links’ to this section
Proposed by Your name linked to your MediaWiki URL, or profile elsewhere on the internet
Preferred group size
Any supplies that you would need to run the session e.g. post-its
Interested attendees (sign up below)

  1. Add your name here

We will be reaching out to the summit participants next week asking them to express their interest in unconference sessions by signing up.

To maintain the consistency, please consider referring to the template of the following task description: https://phabricator.wikimedia.org/T149564.

Trizek-WMF updated the task description. (Show Details)Dec 20 2016, 1:11 PM
Zppix added a subscriber: Zppix.Dec 20 2016, 1:16 PM

Ill be able to remotely review documentation changes if need be i just need time and date

Tgr awarded a token.Dec 23 2016, 1:46 AM
Tgr updated the task description. (Show Details)Dec 23 2016, 2:00 AM
bd808 added a subscriber: bd808.Dec 23 2016, 3:08 PM

I left some notes in T148855#2899052 that may be relevant to this discussion as well:

  • How can we convince people that they "know enough" to contribute to technical documentation?
  • What does "featured article" quality technical documentation look like?
  • Where can we recruit people with professional technical writing experience to become contributors?

More ideas:

  • Who is willing to organize and lead technical documentation edit-a-thons? (Besides @kaldari who seems to be trying to kick one off here.)
  • What tools, styles, templates, etc are we missing to make writing and organizing technical documentation easier?
MusikAnimal updated the task description. (Show Details)Dec 23 2016, 7:16 PM
Xephyr826 updated the task description. (Show Details)Jan 3 2017, 5:56 PM

To the facilitator of this session: We have updated the unconference page with more instructions and faqs. Please review it in detail before the summit: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/Unconference. If there are any questions or confusions, please ask! If your session gets a spot on the schedule, we would like you to read the session guidelines in detail: https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/Session_Guidelines. We would also then expect you to recruit Note-taker(s) 2(min) and 3 (max), Remote Moderator, and Advocate (optional) on the spot before the beginning of your session. Instructions about each role player's task are outlined in the guidelines. The physical version of the role cards will be available in all the session rooms! See you at the summit! :)

Xephyr826 added a comment.EditedJan 12 2017, 11:55 PM

@bd808

Where can we recruit people with professional technical writing experience to become contributors

In North America, the two biggest technical writing professional groups are WriteTheDocs.org and stc.org. There are many people here who are looking to keep their skills sharp and learn more about software development. I believe many people in these groups can be encouraged to contribute to MediaWiki. Both groups have many chapters that meet regularly and a presentation at one of these meetings would go a long way.

I think there's some low-hanging fruit in documentation that's complete but needs a rewrite for clarity.

bd808 added a comment.Jan 17 2017, 3:45 AM

@bd808

Where can we recruit people with professional technical writing experience to become contributors

In North America, the two biggest technical writing professional groups are WriteTheDocs.org and stc.org. There are many people here who are looking to keep their skills sharp and learn more about software development. I believe many people in these groups can be encouraged to contribute to MediaWiki. Both groups have many chapters that meet regularly and a presentation at one of these meetings would go a long way.

Those organizations are great pointers. Thanks for pointing them out.

I think there's some low-hanging fruit in documentation that's complete but needs a rewrite for clarity.

I think this is somehow related to my "What does 'featured article' quality technical documentation look like?" question. We have many contributors who understand what a high quality encyclopedic article looks like, but I think for many of us the benchmark for good technical documentation is still in the realm of "I will know it when I see it".

Xephyr826 added a comment.EditedJan 18 2017, 2:57 AM

@bd808 ,

"What does 'featured article' quality technical documentation look like?"

During the summit, I kept my eye out for good documentation. Two well-documented projects I came across:

In the tech writing field, many people have attempted to answer the question of what makes good documentation. One of my favorite descriptions is the seven C's. Good documentation should contain 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
Qgil triaged this task as Normal priority.Jan 24 2017, 10:59 AM

Did this session happen at the Summit? Is there any additional outcome expected from this task?

@bd808 , @kaldari , @Tgr , @samuwmde , and everyone,

I created a developer wishlist item related to recruiting technical writing professionals to improve documentation. I'm hoping to get your feedback and input: https://phabricator.wikimedia.org/T156301

kaldari closed this task as Resolved.Jan 26 2017, 1:30 AM

@Qgil: No, we didn't end up doing this session at the Summit (mainly because there was a lot of interest in doing wishlist related sessions, so I was busy with that). We may want to recycle it for a future event, however.

Aklapper changed the task status from Resolved to Declined.Jan 26 2017, 2:30 PM

Nothing got resolved, hence closing as declined instead.