Page MenuHomePhabricator

Wikimedia Technical Conference 2019 Session: On-wiki documentation & documentation as code: strengths, weaknesses, and compromises
Open, NormalPublic

Tokens
"Love" token, awarded by waldyrious."Love" token, awarded by Amire80."Meh!" token, awarded by Bmueller."Love" token, awarded by Pavithraes."Love" token, awarded by bd808."Love" token, awarded by Tgr."Like" token, awarded by Samwilson."Meh!" token, awarded by zeljkofilipin."Evil Spooky Haunted Tree" token, awarded by brennen."Yellow Medal" token, awarded by Addshore.
Assigned To
Authored By
debt, Oct 4 2019

Description

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:

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:

Related Issues

Pre-reading for all Participants


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)

Session Scribes

Session Facilitator

Session Style / Format

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)

Post-event summary:

  • Introduction
    • Hello I'm Bryan Davis, Docs, docs, docs. Sarah R. as technical writer since S Page. Worked with Sarah and Alex to think about this space of documentation and distill it down into some things we can make some tangable progress on in an hour.
    • Three questions to do some idea generation around. Not magically sovling problems, not getting into the weeds of tech details. High level tactics and ideas. So others can go back and look at them, and turn into projects.
    • world cafe style. 3 groups, rotate through all three stations as long as we keep moving.
    • the last round should also focus on clustering the elements found during the previous rounds
    • Any questions?
      • Q: 1. Is there any scope limitations - are only talking tecnical documenation or any documentation - tutorials, social, etc?
      • Q: 2. Documentation as code, we all have an idea, what do you personally propose and understand under this umbrella?
        • 1. Technical documentation, API, how to write code to extend or consume other code - Overarching Examples and FAQs are important but not in scope
        • 2. Anything that does not require wiki-edits.
      • Q: is the other direction of doc maintance in scope? Not so easy on gerrit, but easier on wiki.
        • for doc maintanance question yes. Translation and discoverability, orthogonal.
  • Session Questions
    • Documentation 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?
        • cluster: aggragation
          • unifying and centralizing documentation
          • cross wiki search
          • creating a documenation search
          • improving mw.org documentation
        • cluster: consolidate
          • remove outdated documentation
          • define where docs should line/live?. In a single system, not in seperate systems.
          • Add Tags to docs - like labels
          • define clear entrypoints for different steakholders and provide good structure for their needs
          • clear boundaries of software components. a library would have: readme, clear purpose, staffed
          • better version tracking for docs
          • remove duplicate/deprecated docs
        • cluster: Use the content itself to be more discoverable
          • SEO research to improve Google discoverability,
          • make Youtube videos
          • using github byline (repo description area) more actively,
          • link to doc.wm.org from each repo readme
          • use visitor statistics to highlight where your changes are effective etc.
        • cluster: Content organization
          • Structuring the content of documentation to be easier to navigate.
          • High level tutorials (show relevant documentation for problem solving)
          • create documentation that is workflow oriented.
        • cluster: search improvements
          • add option to search external sources to the global-search tool in toolforge
          • cross wiki search of wikitech, mediawiki.org, and meta
          • make docs.wikimedia.org searchable from mediawiki.org
          • transclude markdown files in git repos to the wiki
          • make doc search that merges wiki search and code search
          • improve doc.wikimedia.org portal--design, examples, links to other document collections
          • link to doc.wikimedia.org on Special:APISandbox
          • Crosslink doc.wikimedia.org source and readme
          • list of all doc locations. hub with search forms for each (SUL, wikitech, docs.wm.o, codesearch) or enter text once, click search, and it opens in a new tab for each backend
        • cluster: higher level documents
          • tutorials: people want to solve a problem. show them the relevant documentation based on that problem
          • link to everything from a tutorial
          • create workflow oriented documentation: problem -> find the code -> get into the code -> how to gerrit -> how to get review -> how review works -> have clear workflow
  • Documentation maintenance
    • 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?
      • cluster: Just do it
        • actually update docs
        • implement a process of reviewing docs
        • define per team quality standards for documenting/ set goals to improve
        • just link to repos/document how to contribute docs
        • link to affected docs from gerrit changesets
      • cluster: reduce documentation in wiki
        • Remove all docs from wikis and give up on making that happen
        • make docs visible in IDE so good that documentation elsewhere is less important
        • removing dud????? of on/off wiki by picking one per doc area
      • cluster: automate all the things
        • make it easier to/it is easier to/Autogenerate, documentation on-wiki from code
        • bidirectional git <-> wiki sync on edit
        • sync from git to wiki in the background
        • automate detecting documentation touched/affected by patch
        • autogenerate wiki pages (protected) from code
        • parser function for telling wether a gerrit patch has been merged (and add a maintenance category)
        • having tests be a place to check and validate what docs say is true
      • cluster: unnamed
        • transclude documentation into wiki content from code document (assuming it's better in code)
        • put documentation in the code, allows for contributions like github inbrowser edit (even for non-techs)
      • cluster: who should document/ensure documentation
        • Hiring professionals to write/update the documentation, or poke people to do this (awerness).
        • Or task QA people with this role.
        • organize monthly/quarterly documentation sprints
      • cluster: loose stuff/comments ?
        • QUESTION: how to match knowledge to documentation needs
        • PROBLEM: Translation pings for watchlisted pages are noisy
        • Lead by example and others will follow
        • bind documentation to the version of api/lib
        • Extension.json is hard to document - configurations do have a description need to update to version 2. You can use a specific key (@ sign) for comments (https://www.mediawiki.org/wiki/Manual:Extension_registration#Retaining_documentation)
  • Translation of documentation
    • 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?
      • cluster: using structured data to generate documentation, using translatewiki
        • Translatewiki integration with generated documentation
        • Merge Translatewiki and mediawiki.org to share community
        • have a code comment annotation like @translation {some-string-used-on-translatewiki followed by comment, then end with @endTranslation
        • Translatewiki integration with SWAGGER
        • Structured docs are easier to translate
        • Reduce API, code & programming languages written
      • cluster: make a comparative analysis to see what others are doing in the open source space for document translation
      • cluster: having a single place for translation- move all the docs from the code to the wiki
        • Move documentation from code to wiki
        • sync code documentation with wiki; let it be translated on wiki; have links in ht ecode to the wiki page
        • Put some basic docs from wiki into code; it could be translated there and synced back to the wiki; e.g. extension help page
        • Translating code-docs in the repository itself and update it there
      • cluster: technical solutions - machine generated solutions, using multi content revisions (for what we don't know, doesn't say) <-- Seems covered by line below...
      • cluster: Using MCR to improve the onwiki translations system - onwiki translations can suck because process/system is complicated. MCR might enable several language versions of the same wikipage.
        • Using MCR to store the data pulled from git.
      • cluster: Don't do any translation of code docs - always going to be out of date, and hard to translate
        • move mediawiki.org documentation to the respective repository
        • do not translate code-level docs at all
      • cluster: Celebrate translation 🎊
      • get analytics of people who use machine translation instead of manual translations (can Google share this with us?)
      • measure reach/return on investment for translation of docs by type (e.g. web api docs, tutorials, code internals, etc)
      • Google translate (=automatic translation)
  • Conclusion
    • Bryan thinks it went well! [it did].

Post-event action items:

  • ...

Summary:

  • Accepting the reality that there will be both on-wiki documentation and other general documentation that lives off-wiki.
  • Improving discoverability and workflows
  • Management of off-wiki documentation translations
  • The results of this discussion were sent to full-time technical writers at the Foundation

Event Timeline

debt created this task.Oct 4 2019, 3:19 PM
hashar added a subscriber: hashar.Oct 7 2019, 1:24 PM

Note that from past initiatives we have a developer hub at https://www.mediawiki.org/wiki/Developer_hub which has lot of documentation . It is a fairly wide scope, I am not sure it can be addressed in just one session.

@hashar Hmm, good point. If we were to break the scope down into a couple of more focused discussions, what would you suggest?

Adding both of our Technical Writers on WMF staff here for their feedback/ideas.

@srodlund @apaskulin if you have thoughts on how we would be use some time during this year's Technical Conference on the topic of technical documentation, please share!

Addshore added a subscriber: Addshore.
brennen added a subscriber: brennen.

One suggestion for a focus: Maintenance & cleanup of existing docs. This has come to mind thinking about docs and new developer onboarding - there's a ton of material but it's not always clear how it relates to the current state of things or how to navigate it. Technical debt lives in the documentation as much as anywhere...

One suggestion for a focus: Maintenance & cleanup of existing docs. This has come to mind thinking about docs and new developer onboarding - there's a ton of material but it's not always clear how it relates to the current state of things or how to navigate it. Technical debt lives in the documentation as much as anywhere...

This sounds good to me.

TK-999 added a subscriber: TK-999.Oct 11 2019, 5:10 PM

Something I was thinking about is whether storing developer documentation in an open wiki format on mediawiki.org may be a double edged sword. While this setup allows anyone to edit and improve the documentation, it's not always clear exactly how the documentation should be changed and who should approve changes, if anybody. Storing documentation in a VCS repo, perhaps next to source code even, could be an interesting alternative to consider, as it might allow for an easier review and contribution process. The session could also look at some other open source projects to see how they store and curate documentation.

As far as I have heard, WMF Core Platform Team has some (vague?) ideas about a Developer Portal, which could be worth to share if I'm correct...

josephine_l added a comment.EditedOct 12 2019, 6:02 PM

Storing documentation in a VCS repo, perhaps next to source code even, could be an interesting alternative to consider, as it might allow for an easier review and contribution process. The session could also look at some other open source projects to see how they store and curate documentation.

This could be an interesting option to discuss indeed (the Commons app project currently does this, although our own documentation could do with a lot of improvement). :)

@TK-999 , would you and/or @brennen be interested in leading or co-leading this session? We can start adding specific questions that we want to discuss once we have the leaders in place.

I think I'm correct in thinking that there's already a way to add documentation for arbitrary projects to https://doc.wikimedia.org/ (i.e. not just API docs, but also general user or admin documentation), by using JSDoc and the wmf theme for it. I wonder if one day this could become similar to Read the Docs for Wikimedia tools etc. — e.g. if a Gerrit repo contains a .jsdoc.json file then it's documentation is automatically built and made available online.

@josephine_l Thank you for the offer! However, being a first-time attendee, I'm afraid I am not sure what this would entail and how I should prepare for the task.

@josephine_l I'm primarily attending as a note taker, and should probably focus the time I'm not doing that on local dev and CI sessions. At any rate, I suspect there are considerably better-informed folks than me to lead this one...

Ah, okay. :) Is anyone else interested in leading this? @TK-999 , if you'd like, maybe someone else can lead, and you can co-lead and learn the ropes from them along the way?

Tgr awarded a token.Oct 13 2019, 7:43 PM
Tgr added a subscriber: Tgr.

A documentation portal where you have to learn how to send a Gerrit patch to improve would be a pretty sad development IMO.

There is a Documentation project with lots of relevant tasks; T155024: Store structured data needed for MediaWiki documentation / T155029: MediaWiki.org: Generate infoboxes from extension.json in git is one I'd really love to see move forward, personally. T115650: Create an authoritative and well promoted catalog of Wikimedia tools is another powerful idea that seems to have gotten stuck at some point. There is also a large social aspect (what could we do to have more volunteer technical writers, in terms of outreach, capacity building, appreciation, support etc?).

On the support side, https://discourse-mediawiki.wmflabs.org is now a bit of a "there are now N+1 competing standards" situation, and should be moved forward or discarded IMO (I would of course prefer the former, especially since we seem to be standardizing on Discourse anyway).

Quiddity added a comment.EditedOct 14 2019, 12:09 AM

Thoughts (with obligatory "i am not a dev" disclaimer, and a "sorry for the linkdump, this probably belongs elsewhere, but since you asked..." apology):

Hopefully something in there helps, and doesn't just distract/tangent! Sorry again. >.>

bd808 awarded a token.Oct 15 2019, 2:53 PM

Something I was thinking about is whether storing developer documentation in an open wiki format on mediawiki.org may be a double edged sword. While this setup allows anyone to edit and improve the documentation, it's not always clear exactly how the documentation should be changed and who should approve changes, if anybody. Storing documentation in a VCS repo, perhaps next to source code even, could be an interesting alternative to consider, as it might allow for an easier review and contribution process. The session could also look at some other open source projects to see how they store and curate documentation.

I totally agree with everything said here.
I think if we document alongside code, thus have versioned documentation alongside releases, and expose all of that in some nice standard way we would greatly increase developer on boarding satisfaction, decrease the number of questions that get asked, decrease the wild spread of documentation etc.

I think if we document alongside code, thus have versioned documentation alongside releases, and expose all of that in some nice standard way we would greatly increase developer on boarding satisfaction, decrease the number of questions that get asked, decrease the wild spread of documentation etc.

I agree on these points.

However, I'll just say that the UI for navigating said docs is really important as well. For example we arelady have https://doc.wikimedia.org/mediawiki-core/master/php/ but e.g. clicking on https://doc.wikimedia.org/mediawiki-core/master/php/group__DifferenceEngine.html doesn't really tell me much about how / where / why / when to use DifferenceEngine, or what it is.

@TheDJ I haven't spent a lot of time with Laravel's docs but from what I recall they were pretty straightforward. Other documentation sites I think we could learn from are Symfony's (https://symfony.com/doc/current/index.html) and Stripe's (https://stripe.com/docs), in particular their API reference docs (https://stripe.com/docs/api).

How would we handle translation if we went to a VCS only approach?

Hey all, we are still looking for session leaders in order for this session to go ahead. :) Would anyone like to take it up? @Tgr @Addshore @Quiddity ?

Tgr added a comment.Oct 16 2019, 11:05 AM

I find the claim that a git repo is easier to contribute to and review than a wiki to be dubious, to put it mildly. Wiki changes are very easy to review, it's just that few people care. Even so, I don't recall any example of lack of control causing problems.

IMO there are three problems that a VCS-based documentation portal might solve:

  • synchronizing documentation with master (ie. you can write the docs when you write the patch, and it will show up exactly when the patch is merged). This is a definite pain point with the wiki - I don't want to write docs until I know the patch gets merged, and it's easy to forget afterwards. IMO this can be handled with a wiki just as well, but it requires some thought and establishing the right processes (use something like a gerrit tag to mark if a patch requires documentation, and to keep track of patches which have been merged but not documented).
  • you get documentation for old releases for free. This is somewhat double-edged: it's easy to see docs for a specific version but really hard to get a feel of which versions something existed in (often needed for debugging or deprecation). Also IMO replicable in a wiki with a little discipline.

I'm also dubious that the people who don't write documentation now would magically start once it is expected to be written in the code (which of course is perfectly possible now). We need to improve documentation culture, and I don't feel the medium used for documentation blocks or helps that change much.

An important difference is that you'd need peer review of the changes you're making to the docs (someone to +2 the patch). So yeah maybe "easier" is not the right word, but hopefully more precise / rigorous documentation than the current process where one can casually update Mediawiki.org.

Tgr added a comment.Oct 16 2019, 12:48 PM

FlaggedRevs was used for peer review of mediawiki.org docs changes for a while. It was disabled because it seemed entirely pointless, there weren't enough people interested in reviewing, and was a bit of a solution in search of a problem.

There’s a lot to discuss here, so I think any of the suggested topics would be productive. I can’t speak to the support side, but here are some thoughts on documentation:

Indicating the quality and importance of individual pages

It can be hard for a user to determine how uptodate a page is. It might help if we create & standardize a way we indicate a doc-page's quality and importance?

I think this is a really interesting question and feeds into @brennen’s comment about how a given page relates to the current state of things. Having more context around a page could help new developers feel more confident getting started. I could see a session focusing on defining a helpful scoring system for documentation pages.

Onboarding extension developers
Another topic that came to mind is onboarding for extension developers. The Manual page for developing extensions seems to have some good information, but it's currently marked as outdated. What information should be added (or removed) to support new extension developers?

Doc portal

As far as I have heard, WMF Core Platform Team has some (vague?) ideas about a Developer Portal, which could be worth to share if I'm correct...

Yes! The Core Platform Team is working on an initiative plan for creating a documentation portal for Wikimedia API consumers. If there’s interest, I’d be happy to put together the latest progress and some questions closer to the time of the session.

Session leaders

Hey all, we are still looking for session leaders in order for this session to go ahead. :) Would anyone like to take it up?

I’m assuming session leaders need to be attending the conference?

I’m assuming session leaders need to be attending the conference?

Hi @apaskulin , yes, they do. I don't think we have infrastructure for remote sessions unfortunately.

@josephine_l That makes sense. Thanks for clarifying :)

Hey all, we are still looking for session leaders in order for this session to go ahead. :) Would anyone like to take it up? @Tgr @Addshore @Quiddity ?

I'll primarily be there as a note-taker. I think it is also important for the session-leader to have some understanding of automated documentation (I don't!).

srodlund added a comment.EditedOct 17 2019, 3:41 PM

I would have loved to have had been invited to sit at the table at this conference for this session, because this is the content of my work at WMF. This is an important topic that deserves coverage, AND it is something we have been working on for some time. <3

Over the last year and a half, Dev Advocacy has been working on technical documentation improvements, both creating processes and documentation for folks who want to make quality contributions to technical documentation and making critical improvements to documentation collections.

Maybe you can check out the tech talk I did last month, which outlined some of this work and how to contribute.

https://www.youtube.com/watch?v=GKvyk4VAPb0

Or learn more about the maturity model approach we are trying to take to gauge quality and make improvements -- I would say in the last year, we have made a ton of progress moving from Ad Hoc toward Rudimentary (which is actually really awesome progress, considering we only had one technical writer and the contributions of volunteers, interns and staff who donated time from their own work):

https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation

You could check out the work we've been doing on Google Season of the Docs to help folks become better technical writing contributors. This effort has been driven by a our intern, Pravithaes

https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/#Technical_Documentation

You could look at the last year's work on MediaWiki Action API technical documentation or look at the epic for the ongoing improvements to Toolforge and Cloud VPS documentation.

https://phabricator.wikimedia.org/T198916
https://phabricator.wikimedia.org/T203131

You can also consider our Friends of the Docs working group. It's still in its early stages, but if you join, you can stay up to date on the conversation: https://www.mediawiki.org/wiki/Wikimedia_technical_documentation:_friends_of_the_docs

I'm happy to share more with folks about any of these efforts and future plans, etc.

bd808 added a subscriber: bd808.Oct 17 2019, 9:28 PM

@josephine_l I am talking with @srodlund about this session. If she can put together a focus that participants could constructively help move forward in an hour session I will volunteer to actually lead the session on her behalf. I think having a narrowly scoped topic and a goal for the session is key. Last year's TechConf was very refreshing to attend as most of the sessions were focused and actually activity based as opposed to yet another hour of talking about topic X with no clear goal.

Thus far I see a lot of random idea generation on this ticket about things that could be discussed, but I am not seeing any clearly scoped topics that 1 hour of work by attendees can actually move forward.

One smallish task that might be interesting to discuss is the existing docs in MediaWiki core. There are a bunch of files there that could probably be removed after having their content moved to mediawiki.org (where it could be translated etc.).

Hey @bd808 and @srodlund , that would be fantastic if possible! Could you both confirm that you would like to go ahead with this, ASAP? I think the committee will be removing sessions without a confirmed leader soon.

debt reassigned this task from josephine_l to bd808.Tue, Oct 22, 6:55 PM
debt triaged this task as Normal priority.
debt updated the task description. (Show Details)

Apparently @debt and the committee have decided this is my session to deal with. :)

@srodlund and I had a productive conversation today about any needs that she might have to gather specific feedback from Tech Conf attendees related to her current and planned future work on documentation improvements. We determined that most of the things she is currently interested in are related to end user feedback (the readers/users of documentation) and community building. Neither of these focus areas seems especially well suited to a 60 minute session at Tech Conf.

I will look around a bit more for others who might have topic that we can dig into.

greg added a comment.Wed, Oct 23, 9:36 PM

(Programming note)

This session was accepted and will be scheduled.

Notes to the session leader

  • Please continue to scope this session and post the session's goals and main questions into the task description.
    • If your topic is too big for one session, work with your Program Committee contact to break it down even further.
    • Session descriptions need to be completely finalized by November 1, 2019.
  • Please build your session collaboratively!
    • You should consider breakout groups with report-backs, using posters / post-its to visualize thoughts and themes, or any other collaborative meeting method you like.
    • If you need to have any large group discussions they must be planned out, specific, and focused.
    • A brief summary of your session format will need to go in the associated Phabricator task.
    • Some ideas from the old WMF Team Practices Group.
  • If you have any pre-session suggested reading or any specific ideas that you would like your attendees to think about in advance of your session, please state that explicitly in your session’s task.
    • Please put this at the top of your Phabricator task under the label “Pre-reading for all Participants.”

Notes to those interested in attending this session

(or those wanting to engage before the event because they are not attending)

  • If the session leader is asking for feedback, please engage!
  • Please do any pre-session reading that the leader would like you to do.

(Programming note)
This session was accepted and will be scheduled.

I guess that put some additional pressure on me to actually scope out a useful session. ;)

I have been chatting with @srodlund and @apaskulin and I think we may be getting closer to a focus that can be turned into a participatory 60 minute session that gives actionable feedback. Right now I think the topic will likely be related to an area that @apaskulin credits to @Quiddity -- "Drafting a system for classifying documentation quality". I will continue to post updates here as we narrow in on a session focus and design in advance of the 2019-11-01 deadline.

@bd808 That sounds great! :) Let us know if you need any help.

debt updated the task description. (Show Details)Fri, Oct 25, 9:16 PM

I will continue to post updates here as we narrow in on a session focus and design in advance of the 2019-11-01 deadline.

I met with @apaskulin, @srodlund, and @Pavithraes today. We talked about the previously mentioned "Drafting a system for classifying documentation quality" session idea initially and felt that there are useful points in that general area for feedback from developers but that more work needs to be done from the Technical Writing side to prepare strawdog proposals for review. Idea generation in this area might actually be enjoyable for session participants, but it does not currently seem likely to produce valuable input to the Foundation's tech writers.

We talked about several other possible ideas before hitting on one that seems both engaging and useful to discuss with the type of folks who will be a Tech Conf: docs as code vs docs on wiki. I will be working to refine this idea into a full featured session proposal in the coming days. At a high level we are thinking that the session outputs would be pro/con lists for writing documentation "in code" (reference generated from comments + prose docs kept in git repos alongside code) and for writing documentation on wikis including some thinking about which feels like it works best for different types of documenation, and then idea generation for ways to combine the two approaches effectively to optimize pros and minimize cons. This has relations to the comments in this task like @TK-999 in T234634#5566953, @Tgr in T234634#5571338, @Addshore in T234634#5577951, and @kostajh in T234634#5578671.

bd808 updated the task description. (Show Details)Tue, Oct 29, 6:48 PM
bd808 added a subscriber: CKoerner_WMF.
bd808 renamed this task from Wikimedia Technical Conference 2019 Session: Improving documentation and support channels to Wikimedia Technical Conference 2019 Session: On-wiki documentation & documentation as code: strengths, weaknesses, and compromises.Fri, Nov 1, 5:56 PM
bd808 updated the task description. (Show Details)
bd808 added a comment.Fri, Nov 1, 6:07 PM

I have made major updates to the description for this session with a lot of help from @apaskulin, @Pavithraes, and @srodlund. The session will focus specifically on the reality and challenges of mixing on-wiki and off-wiki documentation in our ecosystem. This scope is much, much narrower than the original proposal. This has been done in an attempt to focus the live 60 minute session at Tech Conf on productive discussion with potentially actionable recommendations for next steps.

I welcome both Tech Conf attendees and the larger Wikimedia community to start listing their ideas related to the 3 questions of discoverability, maintenance, and translation here on this task prior to the session on 2019-11-13. I will attempt to seed the World Cafe discussions with notes derived from that input so that they are included in the summary and next steps reports that will come from the face-to-face work in Atlanta.

Tgr added a subscriber: cscott.Mon, Nov 4, 7:04 AM

Wrt translation, @cscott had a presentation about translatable code comments in Lua modules and such. Not sure if that's in scope since the existing questions are focused on off-wiki code but it's an interesting concept.
Translatewiki's qqq pseudo-language is an interesting hybrid of on-wiki and off-wiki documentation that can be edited both on-wiki and in git. I wonder if that approach could be used more widely.

bd808 updated the task description. (Show Details)Wed, Nov 13, 5:29 AM
Tgr added a comment.Wed, Nov 13, 10:42 PM

One cluster of things that seems like low hanging fruit (useful and easy to do without dedicated staff time) is conventions for Gerrit / wiki sync:

  • Introduce a norm of linking to all affected documentation pages from gerrit changesets
  • Have a maintenance template for tracking pages which will be affected by a pending patch
    • Maybe make a parser function for telling whether a patch is still pending (more effort but still not crazy to have it as community-maintained code)
    • alternatively as a poor man's version use Tool-extjsonuploader and Lua tables for syncing that data
bd808 updated the task description. (Show Details)Wed, Nov 13, 11:07 PM
waldyrious added a subscriber: waldyrious.
josephine_l updated the task description. (Show Details)Fri, Nov 15, 7:17 PM