Page MenuHomePhabricator

Unify product documentation for users to make it easier to share, translate and edit
Open, LowPublic

Description

At the moment, documentation about products is handled by different people, on different teams. There is no rules concerning sections, formatting, useful information for users, etc. like we have rules on Wikipedia or Wiktionary to have a coherent content.

That task would be dedicated to:

  • find out what are the different type of documentation pages we have on mediawiki.org
  • define best practices, or, at least, most common ones to have an unified presentation for documentation
  • ask translators about their practices and preferences concerning translation (page length, formatting...)
  • connect that project to Shadow namespaces, to transclude documentation to all wikis (T91162)

That task is not dedicated to:

  • developers' documentation
  • how to install Mediawiki or extensions.

Related

Related Objects

StatusSubtypeAssignedTask
DuplicateQgil
ResolvedQgil
ResolvedQgil
OpenNone
OpenNone
ResolvedPppery
ResolvedJohan
ResolvedJohan
ResolvedTrizek-WMF
OpenNone
ResolvedTrizek-WMF
ResolvedTrizek-WMF
ResolvedTrizek-WMF
Resolved jmatazzoni
Resolved jmatazzoni
Resolved jmatazzoni
ResolvedTrizek-WMF
ResolvedTrizek-WMF
ResolvedMtDu
OpenNone

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes
Trizek-WMF set Security to None.
Trizek-WMF subscribed.
Trizek-WMF raised the priority of this task from Medium to High.Mar 4 2016, 4:05 PM
Trizek-WMF renamed this task from Q3 personal goal: Work on unifying product documentation to make it easier to share, translate and edit to Goal: Work on unifying product documentation to make it easier to share, translate and edit.Mar 7 2016, 10:41 AM

This task fits with T131883: Communication workflows between WMF Product teams and Wikimedia communities and specifically this measurement of success:

  • Product page template reflecting PDP status and history.

@Trizek-WMF @Keegan do you think you can align this task with that goal?

@Qgil, yes T121500 fits with T121500. I'm afraid you missed a copy/pasting action :)

Yeah, some things are in common, but the par concerning unifying help pages for example is missing. At the moment, all help pages are different, and we don't know what is the best layout for translators.

Should we merge anyway? Or split? Or rename that task?

If this is about documentation only (Help pages and "static" information about products, then it is not worth mixing it with the PDP really. If product development information is within the scope of this task then yes, let's mix it.

After reading your comments and looking at the task again,. maybe it is better to have you and this task focusing on user documentation, and then create a task (if none exists yet) about project documentation, which would be the blocker for T131883.

Yes, that's more about documentation: how to write it, where, how, how to get it translated. PDP is an other thing.

There is no rules concerning sections, formatting, useful information for users, etc.

The existing rules at at https://www.mediawiki.org/wiki/Project:PD_help .

There is no rules concerning sections, formatting, useful information for users, etc.

The existing rules at at https://www.mediawiki.org/wiki/Project:PD_help .

I didn't knew about that, thanks a lot!

Trizek-WMF lowered the priority of this task from High to Medium.May 10 2016, 2:52 PM

We are discussing this task as a potential team quarterly goal (T131915). I think we would need to re-scope it a bit in order to address a basic problem: projects jumping to prioritization and development (requesting significant resources) without a standard project information explaining what problems is the project solving, what research has been done about alternatives, what are the goals, etc.

By "re-scoping" I mean to include these aspects of project information, without removing any of the goals mentioned currently in the description. All of them are connected. If this doesn't work, then let's create separate tasks.

For reference, see Technical_Collaboration_Guideline/Vision#Project_information and this related discussion.

After re-reading the discussion of this task and thinking about more, I believe it is probably better to have a subtask dedicated exclusively to best practices on project information in relation to the Technical Collaboration Guideline recommendation. This task here includes user documentation like Help pages, and that is a totally different beast.

Trizek-WMF lowered the priority of this task from Medium to Low.Jun 14 2016, 11:24 AM
Trizek-WMF raised the priority of this task from Low to Needs Triage.

I remove myself as an assignee to that task: no time to work on that (where is my clone?) and more important priorities to focus on first (translations, Collaboration team products...).

Actually, after re-reading the description I think that there is a chance that this task could be (part of) an Outreachy internship, if there are mentors willing to push for it.

Qgil renamed this task from Goal: Work on unifying product documentation to make it easier to share, translate and edit to Unify product documentation to make it easier to share, translate and edit.Sep 28 2016, 7:20 AM

@Qgil We are rounding up projects for GSoC/Outreachy for May-Aug 2017. You had mentioned that this could be an internship project. Would you like to mentor or can suggest possible mentors? For potential mentors, please add yourself as "Mentor: <username>" in the task description, and tag this task with Outreach-Programs-Projects

@Qgil We are rounding up projects for GSoC/Outreachy for May-Aug 2017. You had mentioned that this could be an internship project. Would you like to mentor or can suggest possible mentors? For potential mentors, please add yourself as "Mentor: <username>" in the task description, and tag this task with Outreach-Programs-Projects

i think the two sub-tasks (or deeper) can be possible projects:

What a mentor is supposed to do? Is it required to be a developer?

See an email in your inbox "GSOC 2017/ Outreachy Round 14: Interested in being a mentor?" :)

@Trizek-WMF hey! so for an outreach program project, we need to have two mentors with at least one having prior experience with our projects. The Outreachy program especially involves not just coding related projects but also design, documentation, marketing, etc. So, the projects you are proposing could be a great fit!

These tasks would require a bit of technical implementation, right? So you could perhaps mentor for the documentation and somebody else could mentor for the technical part. Would you be interested? Do you have anybody else in mind who could mentor along with you?

A typical project should take about 2-3 weeks for an experienced contributor, and 3 months for a beginner.

These tasks would require a bit of technical implementation, right? So you could perhaps mentor for the documentation and somebody else could mentor for the technical part. Would you be interested? Do you have anybody else in mind who could mentor along with you?

The project is 95% technical and I have no idea of someone who may have time to support the technical side. :/ I'll search for someone.

Trizek-WMF renamed this task from Unify product documentation to make it easier to share, translate and edit to Unify product documentation for users to make it easier to share, translate and edit.Nov 27 2017, 9:41 AM
Trizek-WMF moved this task from Backlog to For MediaWiki users on the Documentation board.
Trizek-WMF updated the task description. (Show Details)

Tagging open CommRel-Documentation tasks with MoveComms-Support as Community-Relations does not exist anymore per https://phabricator.wikimedia.org/project/profile/3448/ . Feel free to set the task status to declined or invalid if this task is not valid anymore and/or if the team moved from public Phabricator to internal WMF tools to plan or manage its work.