Page MenuHomePhabricator

Engage developer documentation task force
Closed, DuplicatePublic

Description

How can we engage with the communities to develop content? T304: Developer Hub contribution process has the procedure for writing articles.

Measurement of success

Dependency

ETA

Relation with WMF Call to Action

Event Timeline

Spage raised the priority of this task from to Needs Triage.
Spage updated the task description. (Show Details)
Spage added subscribers: Spage, Qgil.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJun 30 2015, 3:11 AM
Spage renamed this task from Engage documentation task force to write developer doc to Engage developer documentation task force.Jun 30 2015, 3:13 AM
Spage set Security to None.
Qgil renamed this task from Engage developer documentation task force to Goal: Engage developer documentation task force.Jul 1 2015, 2:53 PM
Qgil updated the task description. (Show Details)
Qgil added a project: ECT-July-2015.
Qgil claimed this task.Jul 7 2015, 9:44 AM

I'll take the ownership of this one, even if it is still a shared goal. S focuses on content, I focus on people.

Qgil triaged this task as Low priority.Jul 7 2015, 9:45 AM
Qgil raised the priority of this task from Low to Normal.Aug 27 2015, 11:19 AM
Qgil reassigned this task from Qgil to Spage.Sep 16 2015, 12:32 PM

@Spage and I didn't have time to focus on this goal during this quarter. We are transforming it in a goal for the next quarter, opening the question of how should this documentation task for be created, and aiming to have a session proposal for the Wikimedia-Developer-Summit-2016. More to come in the following days.

Qgil removed Spage as the assignee of this task.Jan 12 2016, 7:26 AM
Qgil lowered the priority of this task from Normal to Low.
Qgil added a project: Documentation.
bd808 added a subscriber: bd808.Feb 10 2016, 8:17 PM
Qgil renamed this task from Goal: Engage developer documentation task force to Engage developer documentation task force.Sep 28 2016, 8:12 PM
Qgil removed a project: Goal.

I fail to see a problem description in this task. Or measures of success. And what "engaging" would solve, to not engage for the sake of engaging.

If I get it right, this task is about finding more volunteer / 3rd party developers to write/maintain/update/create development related content? Which underlying problem would that solve?

So currently I'm proposing to decline this task.

bd808 added a comment.Oct 5 2016, 3:37 PM

Here's something related that a few of us drafted in an etherpad months ago that never went any further:

== Help us spread knowledge about accessing and reusing Wikimedia's knowledge ==

Have you or someone you know ever struggled with the MediaWiki docs when writing a bot or a script to access wiki content?  Have you ever said to yourself, "I wish I could help fix that"?  You can!

The MediaWiki software developer community needs your help! The Action API (api.php) is the gateway to the knowledge contained in Wikimedia projects and thousands of other MediaWiki wikis for software developers. Amazing products can be built based on the data that the Action API exposes to the world. The problem we face today is that learning what is possible and how to get started using the Action API is harder than it should be.

Developers and others have created a lot of documentation (<https://www.mediawiki.org/wiki/API:Main_page>, <https://en.wikipedia.org/w/api.php?action=help&recursivesubmodules=1>) about the software they help develop. The gory details are all there, but the nice introductions and step by step tutorials are generally missing. The skill set that makes a great software developer doesn't have a large overlap with the skill set that makes a a good tutorial writer or information architect. That's where some of you reading this message can help.

We need everything from a good landing page to easy navigation of all materials. From a comprehensive developer reference to a set of tutorials for first time users, it all needs to be organized, updated, completed, or perhaps even written for the first time.  Interested?  You don't have to sign up, just start editing!  But you can sign up here [...] and coordinate your work with others too.
( let's make a page so folks interested can communicate and get recognition too, what do you think?)
( Maybe we could revive <https://www.mediawiki.org/wiki/Project:Manual> ?)

If you want to work on correcting the existing docs, here are some places to start:
* missing/out of date examples
* unclear dependencies
* bad info on old versions!

If you're excited about adding new documentation, here are some ideas:
* Easier to use examples / integration with api sandbox?
* new vs old API format in examples (ugh!)
* high-level usage examples using libs/frameworks?
bd808 added a subscriber: Mooeypoo.Oct 5 2016, 3:39 PM

I think @Mooeypoo is interested in this general topic as well.

Qgil added a comment.Oct 5 2016, 8:19 PM

This was an individual quarterly goal for S Page when he was our Tech Writer working on Web-APIs-Hub . The idea was that having a professional tech writer is great, but iit would be even better to have that tech writer building up and consolidating a task force of volunteers focusing on developer documentation. Now we don't have a professional tech writer, and there is no task force either, and the progress on documentation tasks is basically unknown, if not inexistent. Which kind of proves the need to have this task force.

I would keep this task open and see if we can put something together. Our new Developer Advocate will not be able to solve all the problems at once, but maybe this is one area where they can push some progress at some point. If others have ideas too (thank you!) please keep sharing them here.

I've been wondering for a while about an idea regarding creating and working on our more "entry point" tutorials and documentation pieces.

@Qgil, is it possible and worthwhile to create some documentation / tutorial-writing project as part of outreachy? That internship supports documentation and technical writing projects, and we could create a project that results with a few beginner tutorials that help new developers get into our development environment as a sort of pilot on getting some targeted guides done.

It could start with things like installing and managing Vagrant in the different OS platforms, working with Git, what's our code style and what linters we use, how to set up grunt tasks for our repos, Git review/Gerrit, etc. The documentation that currently exists can be a bit cold, technical and distributed, and some of it assumes prior knowledge not all new devs have.

I'd be willing to co-mentor something like this, if you think it could work.

Thanks for the updates everyone! Made me pretty happy to see people having thoughts and caring.
I hope I didn't sound too negative yesterday when commenting here.

The idea was that having a professional tech writer is great, but it would be even better to have that tech writer building up and consolidating a task force of volunteers focusing on developer documentation.

Heh, and having a bugwrangler create a task force of volunteers to triage bugs, and having a developer create a task force of volunteers to write and edit code, and... ;) So yeah I look forward to having a Developer Advocate soon!

the progress on documentation tasks is basically unknown, if not inexistent. Which kind of proves the need to have this task force.

Maybe but not necessarily. It might also prove that we do not have enough automation when creating documentation (like API references created from code comments, not being duplicated on wiki pages that quickly get outdated). Or that we miss a style guide what [not] to include in docs. Or that we do not refuse code changes which do not include or update documentation. Or that we simply have too many docs (which would totally be in scope again for a task force). Or stuff like that.

I would keep this task open and see if we can put something together. Our new Developer Advocate will not be able to solve all the problems at once, but maybe this is one area where they can push some progress at some point. If others have ideas too (thank you!) please keep sharing them here.

Indeed, makes sense (and I cannot come up with a better task summary either on this morning). Thanks!

If you're excited about adding new documentation, here are some ideas:

  • Easier to use examples / integration with api sandbox?
  • new vs old API format in examples (ugh!)
  • high-level usage examples using libs/frameworks?

Yeah, having well-defined areas to work on (like a search term or category in case of on-wiki providing a list of docs which still list/recommend using some deprecated function etc) to cut this into pieces sounds good. Or automation when possible (bots replacing content) and feasible? :-/

I've been wondering for a while about an idea regarding creating and working on our more "entry point" tutorials and documentation pieces.
[...]
We could create a project that results with a few beginner tutorials that help new developers get into our development environment as a sort of pilot on getting some targeted guides done.
It could start with things like installing and managing Vagrant in the different OS platforms, working with Git, what's our code style and what linters we use, how to set up grunt tasks for our repos, Git review/Gerrit, etc. The documentation that currently exists can be a bit cold, technical and distributed, and some of it assumes prior knowledge not all new devs have.

I share the sentiment as we throw dozens of links onto new contributors.
Confession: I believe we have too much documentation.
And I believe I have seen patterns (not only in Wikimedia but also in other FOSS projects using wikis for docs) of

  1. "The guide is too complicated so I'll write a simpler guide for newcomers from scratch"
  2. Other people organically adding stuff as "This topic feels important but isn't covered in that new guide so I'll add it"
  3. Go back to 1. to play another round; watch guides become outdated as people only update the two guides they are aware of; see newcomers find guides that are not among those two and hence are older and outdated; have newcomers fail.

Having an Outreachy project sounds awesome, if the existing docs got improved, if we don't completely overwhelm the student (how to not spend 6 out of 12 weeks reading gazillions of text pages to get a grip what's in store?), and if we manage to cut this into actionable subtasks. Somehow. :)

Qgil added a comment.Oct 27 2016, 1:26 PM

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 added a subscriber: Xephyr826.Jan 10 2017, 6:47 PM
Qgil added a comment.Jan 17 2017, 8:49 AM

If we define a more specific goal i.e. "Create a developer documentation working group", then we could propose it at Developer-Wishlist (2017) and see how much interest it gets.