=Session=
* Track: Local Development and onboarding
* Topic: On-wiki documentation & documentation as code: strengths, weaknesses, and compromises
* Location: Azalea room
* Time: Wednesday 2019-11-13 13:30 EST
=Description=
Wikimedia technical documentation lives both on wiki (mediawiki.org, wikitech.wikimedia.org, meta.wikimedia.org, etc) and off wiki (through the source repository, https://doc.wikimedia.org/, etc). In this session, we’ll compare the advantages and disadvantages of these two approaches and discuss ways to improve the experience for both.
=Questions to answer and discuss=
==Discoverability==
On-wiki docs are searchable within a single wiki, but these searches don’t include content from other wikis or from off-wiki docs. How can we improve the discoverability of off-wiki docs?
**Discussion topics:**
* Creating on-wiki landing pages that link to off-wiki docs.
* Transcluding off-wiki docs into wiki pages
** Example extension: https://www.mediawiki.org/wiki/Extension:GitHub
** Technical challenges
*** Update process
*** Caching
*** Security
* Expanding the reach of search to include content across wikis or across sources
** Code search: https://codesearch.wmflabs.org/search/
==Maintenance==
When docs are stored in the same repository as the code they describe, either as separate files, code comments, or generated using a tool, doc updates can be made in the same patch as code updates. In this case, code reviewers should request that patch authors add docs if needed before patches are merged. For docs stored on-wiki, it can be more difficult to keep the docs in sync with code changes. What workflow improvements could be made to make on-wiki docs easier to maintain?
**Discussion topics:**
* Linking to applicable wiki pages in code comments
* Continuous integration that looks for the patch ID in an edit summary
* Publishing wiki docs with an “open patch” label that can be removed once the patch is merged
==Translation==
While on-wiki docs can take advantage of established translation workflows, translation for off-wiki docs can be challenging to support. What processes or tooling can we put in place to make translation easier for off-wiki docs?
**Discussion topics:**
* Example: The generated docs for MediaWiki Action API support localization through https://gerrit.wikimedia.org/r/plugins/gitiles/mediawiki/core/+/master/includes/api/i18n
* Publish guidelines for off-wikis docs wanting to support translation
=Related Issues=
* {T91626}
* {T155024}
* {T155029}
* {T222479}
* {T157757}
=Pre-reading for all Participants=
* [[https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/Technical_documentation_templates_and_suggestions|Technical documentation templates and suggestions]]: Overview of various technical documentation types and their characteristics
* [[https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/Technical_writer_guide|Technical writer guide]]
* [[https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation|Maturity model for MediaWiki technical documentation]]
----
=Notes document(s)=
https://etherpad.wikimedia.org/p/WMTC19-T234634
=Notes and Facilitation guidance=
https://www.mediawiki.org/wiki/Wikimedia_Technical_Conference/2019/NotesandFacilitation
----
=Session Leader(s)=
* Bryan Davis (@bd808)
=Session Scribes=
* Chris Koerner (@CKoerner_WMF)
=Session Facilitator=
* Deb Tankersley (@debt)
=Session Style / Format=
[[http://www.theworldcafe.com/key-concepts-resources/world-cafe-method/|World Cafe]] discussion and list generation.
The room will be setup with 3 stations, one for each of the Discovery, Creation, and Translation topics. Participants will be divided into 3 groups, one for each station, and rotate through the stations with 10 minutes for each group to discuss each topic. The goal of each group during each rotation should be to generate new ideas related to the station's topic, build on existing ideas left by prior groups, and cluster ideas which are similar in approach. During the final rotation, the goal expands to include producing a high level summary of the ideas generated in all 3 rotations to be used in a 5 minute summary to the whole room in the report back phase.
**Tentative agenda:**
* Welcome and introduction (10m)
* World Cafe round 1 (10m)
* World Cafe round 2 (10m)
* World Cafe round 3 (10m)
* World Cafe report back (15m)
* Wrap up and next steps (5m)
----
**Session Leaders** please:
[x] Add more details to this task description.
[] Coordinate any pre-event discussions (here on Phab, IRC, email, hangout, etc).
[x] Outline the plan for discussing this topic at the event.
[] Optionally, include what this session will //not// try to solve.
[] Update this task with summaries of any pre-event discussions.
[] Include ways for people not attending to be involved in discussions before the event and afterwards.
----
Post-event summary:
* ...
Post-event action items:
* ...