It would be great to see more documentation writing; this seems like a good plan to catalyze that. I'm not sure it fits into the developer wishlist as the goal there is to have a list of tasks that would improve the work environment of developers; so that would be "have better documentation", not "recruit documentation writers" (except that "have better documentation" is of course too vague). Recruiting documentation writers is a startegy for tackling those tasks.

So IMO it would be worth creating a bunch of devrel tasks for specific documentation areas which you found lacking, and the feedback on those could be used to orient the events/people discussed in this task.

This was in some sense forked out of discussion on T149372: MediaWiki Documentation which was a Dev Summit session that didn't happen due to time/scheduling. If we can't ultimately figure out how to tie this into the Dev Wishlist I would be interested in trying to help run a pilot project with Cloud-Services and Toolforge where we know that we have a lack of tutorial content and some specific asks from the past Tool Labs user surveys that we could try to organize around. I think that @Mooeypoo and @Quiddity may have other ideas of specific things that could use attention.

Thanks for this proposal, @Xephyr826. I have merged T104286 because this task here is more complete since the start. Good!

Even if this is not one of those tasks that someone would solve during a weekend, I still think that it is a good candidate for the Developer Wishlist. The support it gets compared with other wishes will help us prioritizing it consequently.

Thanks for the input everyone.

@Tgr

So IMO it would be worth creating a bunch of devrel tasks for specific documentation areas which you found lacking, and the feedback on those could be used to orient the events/people discussed in this task.

Totally agree. We'll get many specific items from other tasks in the Documentation column of the developer wishlist. The question this topic helps answer is, once we identify specific documentation issues, who's going to work on them? As you said, this is a strategy for dealing with those tasks.

This wishlist item boils down to two things: Outreach and onboarding.

@bd808

I would be interested in trying to help run a pilot project with Labs and Tool-Labs where we know that we have a lack of tutorial content and some specific asks from the past Tool Labs user surveys that we could try to organize around.

I think this is exactly the kind of thing it would be effective to organize around.

The vision I've kind of have in my mind is this: After some outreach, we'll have a group of people interested specifically in writing documentation. Instead of sending them to Easy Doc Bugs, which is intimidating and hard to parse, let's connect them directly with people, projects, and mentors who can provide guidance on what to work on.

I attended the summit session Better recommending of tasks suitable for new technical contributors (T149564), and the thing that stayed with me is that it's the connections with people that encourages new contributors.

"Find more people to help with documentation" is a vague goal, especially with the Developer Wishlist in mind. What about "Create a developer documentation task force". Or "working group".

@Qgil Are there any models for task forces in other areas? If we gather a group of writers and devs, do you have any suggestions for how to organize?

In T156301#2975445, @Qgil wrote:

"Find more people to help with documentation" is a vague goal, especially with the Developer Wishlist in mind. What about "Create a developer documentation task force". Or "working group".

This is probably something that can be split into a separate conversation, but I have some thoughts on terms that we could use. The Kubernetes community has two types of groups:

• Special interest groups which are long standing groups of volunteers interesting in working on a particular aspect of the project (e.g. API, CLI, Auth, Docs). There are well defined expectations for how a SIG operates and a directory of SIGs that make getting involved relatively simple.
• Working groups which are similar to SIGs, but formed to address a particular time bounded issue rather than a broad area of interest in the community. In a Wikimedia context a WG could be used to do something like organize a hackathon or implement a single technical RfC.

I like this distinction between long standing and task focused sub-communities. I also like that the term "special interest group" is fairly self-explanatory and shares terminology other organizations such as the Association for Computing Machinery, Kubernetes, CentOS, etc (https://www.google.com/search?q=special+interest+group).

I like the idea of special interest groups, it makes sense.

@Xephyr826, about useful precedents in our community, I am not sure, but other with a better memory can correct me. I think we have been leaning toward process-heavier types of groups, like the Architecture Committee or the MediaWiki Stakeholders Group, but I don't think this is what we need here.

Having a group in charge of triaging / grooming the Documentation workboard, identifying top priorities, and organizing activities (including lobbying to the Wikimedia Foundation) in order to complete the top priorities... that would be already a huge step. Doable.

Thanks, @bd808 , @Qgil I modified the description according to your comments.

Do you have any other suggestions for making this wishlist item more appealing and likely to gain traction?

In T156301#2995064, @Xephyr826 wrote:

Do you have any other suggestions for making this wishlist item more appealing and likely to gain traction?

I took a shot at making the problem statement and SIG suggestion a bit more exciting. :)

It would be nice to follow up on @Tgr's feedback in T156301#2971300 and see if someone can come up with a few specific initial projects that could be worked on as well. I would suggest that the content we are most missing is in the area of tutorials and how to's on topics like "Create your first extension/special page/api action/parser hook/library/gadget/tool/bot", "Handling lag when making Action API calls", "ABC's of using Action API continuations", "Converting your special page to OOjs UI", "MediaWiki database abstractions for beginners", etc.

I made a few suggestions in T148855#2897924 on how the self-documentation capabilities of the API could be better utilized; I'd be curious to hear what people think of that.

In T156301#2995266, @Tgr wrote:

I made a few suggestions in T148855#2897924 on how the self-documentation capabilities of the API could be better utilized; I'd be curious to hear what people think of that.

I already replied there; in short, I dislike the suggestion to turn Special:ApiSandbox into the canonical source of documentation and discussion.

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.

This request ranked #41 out of 76 in the Developer Wishlist Survey results. with 11 votes. This alone doesn't indicate a high priority... unless those 11 people want to be actively involved, then we have plenty of support. :)

In the wikipage, @Nemo_bis says:

I thought it already existed. :) Project:PD help, Project:WikiProject Extensions and Project:WikiProject Bug Squad are similar; is this just a proposal to create yet another such project but with a much larger scope?

As I understand this proposal, the emphasis is on creating a "group" (of people). Although these WikiProjects have a relation with documentation, none of them have an identified and active group of people behind them right now. I think this interest group, those WikiProjects, the Documentation tag/board in Phabricator... are all compatible. However, progress in all these areas is likely to be better if there is an organized group of people behind.

I am definitely interested in helping get a group interested in actively working to improve docs off the ground. I think @Nemo_bis is right that such efforts have certainly been started before, and some have been more successful than others. I think that @Xephyr826 has some interesting ideas on wiki about connecting with technical writers and engaging them in contributing.

I talked to a local WriteTheDocs meetup group recently and found that there were several people with some interest. When I was asked by one interested party about how to get started, the list of "getting started" tasks I came up with was pretty daunting:

The first thing I would suggest is poking around our two developer
centered wikis:
* <https://www.mediawiki.org/wiki/MediaWiki>
* <https://wikitech.wikimedia.org/wiki/Main_Page>

The first is broadly about MediaWiki and our other FLOSS software
projects. The second is for operational docs about our production
network *and* docs on "Labs" (our infrastructure as a service product)
and "Tool Labs" (our shared hosting/platform as a service product).

Then you probably should try creating yourself a couple of user
accounts. For stupid reasons that I'm working on eliminating, wikitech
uses a different authentication backend from mediawiki and the rest of
the Wikimedia wikis (wikipedia, wikisource, wikiversity, ...).

Creating a "unified account" is pretty simple. Just click the "create
account" link at the top right on mediawiki.org and fill out the form.
Your username can be a pseudo anonymous handle or your real name and
can contain whitespace.

There is a shiny new system for creating "technical contributor"
accounts that are used on wikitech and many other non-wiki products
like our code review system (<https://gerrit.wikimedia.org>) and bug
tracker (<https://phabricator.wikimedia.org/>). The only place that I
have updated the docs for this so far is at
<https://wikitech.wikimedia.org/wiki/Help:Tool_Labs#Quick_start>, but
it should really be easy to go to
<https://toolsadmin.wikimedia.org/register/> and follow the prompts.
The system there has you start by authenticating with your "unified
account" and then tries to guide you through the rest of the required
inputs.

Once you get through all of that (whew!), you are all set to start
editing things! You may have noticed things by this point that you
want to fix up. If you aren't familiar with wiki editing you may want
to get started with a few small edits here and there to fix up
spelling and grammar or just reword awkward sentences.

Another way to get comfortable is by editing things as sub-pages of
your user page (<https://www.mediawiki.org/wiki/Help:User_page>). It
would actually be neat to see a write up of what you did and how it
worked for you to get that far in the process. I think I mentioned at
the meeting that one of the things our docs often lack is "beginners
mind". Often by the time that someone feels comfortable writing things
down they have forgotten a lot of the weird bumps that they passed
over when getting started.

When you are ready for bigger things, we have a lot of bugs in our bug
tracker about things that have missing or poor docs. Go over to
<https://phabricator.wikimedia.org/>, create an account using either
your unified or technical contributor account, and take a look at:
* <https://phabricator.wikimedia.org/project/view/987/> (workboard for
things tagged "Documentation")

You might also be interested in:
* A proposal to create a SIG for documentation:
<https://phabricator.wikimedia.org/T156301>
* The "Documentation" column on
<https://phabricator.wikimedia.org/project/view/2436/> which was a
very recent project to collect ideas about things that developers
would like to see fixed.
* The collection of docs I'm most desperate to see improved:
<https://wikitech.wikimedia.org/wiki/Portal:Tool_Labs>

@bd808, I'm also interested in working to continue this group. I'm glad to see you saw some interest from Write the Docs! I'm part of Write the Docs San Francisco. In May, I'm booked to give a presentation on contributing to MediaWiki and I hope to encourage other writers to join.

I'm ready to start working on some doc tasks for tools, and I thought I'd start with T134495 (my first Pywikibot bot).

Thanks for posting your "getting started" list. It's daunting but useful. I think it'll help to clearly indicate or link to some procedures: "Create a MediaWiki.org account", "Find a task to work on", "Get to know Phabricator", "Creating documentation drafts"

Getting a Documentation SIG up and running is currently part of the Technical community building program in the FY17/18 draft annual plan for the Wikimedia Technology department. I am the "owner" of that program, and I look forward to working with anyone who is interested to come up with a light weight framework for organizing the SIG and attracting participation. As the manager of the new Cloud Services team I have a vested interest in improving the technical documentation for Cloud-Services and Toolforge, but I think the scope of the SIG can and should extend to the broader technical documentation needs of the Wikimedia movement.

Great news! How can Developer-Advocacy help?

Getting a Documentation SIG up and running

Is there some advice anywhere on what makes a SIG?

In T156301#3217337, @Nemo_bis wrote:

Getting a Documentation SIG up and running

Is there some advice anywhere on what makes a SIG?

I think that is the first sub-task that we need to work on. I would suggest that we survey the documentation of other organizations that use the Special Interest Group model, create a list of possible requirements/behaviors/activities for such groups, and adopt some initial guidelines for forming and operating a Wikimedia SIG. If we want to model something like the Kubernetes SIG system the right path is probably drafting and discussing a technical RfC through the TechCom-RFC process.

It would be useful to check https://www.mediawiki.org/wiki/Architecture_committee/Charter and clarify whether this Documentation Special Interest Group and technical documentation in general would be within scope of the new Technical Committee.

I have asked at https://www.mediawiki.org/wiki/Topic:Ts27ky0skjbfdlb0

@Xephyr826: Why was this task declined?

It should be either closed as resolved or kept open, IMO, depending on whether you think the Technical Document Re-working Group fits the task description or is (for now) too narrowly scoped.

In T156301#4059934, @Tgr wrote:

It should be either closed as resolved or kept open, IMO, depending on whether you think the Technical Document Re-working Group fits the task description or is (for now) too narrowly scoped.

What's the "technical document" referred by the name? The page doesn't explain.