@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).

Relevant: T131516: Reduce or eliminate the need for the user to touch <translate> tags and unit markers

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

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

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

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. :)

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?

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

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.

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?

@johl

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

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.

+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).

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.

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

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?

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! :)

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

In T149372#2937263, @Xephyr826 wrote:

@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".

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

• https://www.mediawiki.org/wiki/Extension:Echo
• https://www.mediawiki.org/wiki/Extension:Cargo

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

@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