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!

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...

In T234634#5565267, @brennen wrote:

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.

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...

I'll just say: https://laravel.com/docs/6.x again ;)

In T234634#5566953, @TK-999 wrote:

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?

@Quiddity thoughts here?

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).

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

• The Documentation tag's workboard has benefited from a recent major sorting effort by @srodlund (ty!). Other people assisting with that, regularly, and thus also becoming familiar with the individual tasks in the backlogs and offering input on them (or pointing other people towards them), would be great.
• High-level on-wiki documentation overviews: There are various ongoing and past efforts to create hubs - organized overviews of the most fundamental/important pages. More people assisting with those would be great (give ideas, ask questions, give feedback, etc).
  • Existing wikipage efforts
    • The mainpage at mw.o was overhauled recently. https://www.mediawiki.org/wiki/MediaWiki
    • The developer hub is important and could always use more eyeballs/watchlisters/editors. https://www.mediawiki.org/wiki/Developer_hub
    • The page https://www.mediawiki.org/wiki/How_to_become_a_MediaWiki_hacker is the 3rd crucial hub, one that most newcomers are directed towards.
    • All would benefit from improvements to all the pages they link to.
  • Ongoing/future/historic wikipage efforts
    • The six "User pages" links at the bottom of https://www.mediawiki.org/wiki/User:APaskulin_(WMF) are among the most useful/relevant.
    • The ongoing GSoD work of https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/ is also very important
    • I made a list a couple of years ago at https://www.mediawiki.org/wiki/User:Quiddity_(WMF)/Hubs_and_docs which might be useful
• Individual wikipages:
  • 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?
    • Currently we just use these generic cleanup templates: https://www.mediawiki.org/wiki/Documentation/Style_guide/templates
    • Perhaps we want to use some sort of scoring-system, like the Wikipedia's sometimes use "stub/start/c/b/a/good/featured" (quality) and "top/high/mid/low" (importance) type ratings?
    • See also https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/Technical_documentation_prioritization
• Off-wiki and Cross-wiki docs and tools:
  • Self-documenting code, annotated source-code, docs.wikimedia.org, etc - I don't know anything about these.
  • Wikitech vs Mediawiki - this is always complicated, due to the historical/idealistic split of wiki-roles. Nothing that can be done, for now. Wikitech should be SUL eventually, which will improve things a bit.
  • I keep a list of seemingly-important links & subdomains at https://wikitech.wikimedia.org/wiki/User:Quiddity#Bookmarks (which might be relevant here. I regularly forget what they're all for!)
• Other:
  • There's probably still some good ideas worth more discussion/effort at https://www.mediawiki.org/wiki/Developer_Wishlist/2017/Documentation
  • This group was recently renamed/rebooted/opened-up, and everyone should watchlist it (for now. More info/outreach soon): https://www.mediawiki.org/wiki/Wikimedia_technical_documentation:_friends_of_the_docs
    • There's a listing of external "good docs examples" reference material that anyone can add to at (the group's old name) https://www.mediawiki.org/wiki/Technical_Document_Re-working_Group/Resources
• Support channels:
  • Complicated, because different methods/platforms are best suited to (A) different types of questions, (B) different archetypes of users. Plus (C) the people with the knowledge to answer a question might not be in (nor want to be in) the chosen platform. E.g. An inexperienced newcomer who is slowly learning how a code-review system works, needs different support from an experienced newcomer who needs to understand how our platforms relate to what they learned elsewhere. -- The platforms themselves (Onwiki/Discourse discussion; VS Mailing-list discussion; VS IRC/Telegram/Zulip discussion) each have different pros/cons, too, such as searchability, filterability (the usual cause of channel-fragmentation or an individual just leaving a channel, is trying improve the signal-to-noise ratio for themselves), difficulty of joining-in, and speed-of-average-response.
• Conference idea:
  • Perhaps discussing the specific types of documentation that we're most in need of (improving or creating), would be helpful?
    • See TLDR of the types at https://www.mediawiki.org/wiki/Documentation/Style_guide#Deciding_on_a_document_type
    • and a list of accurate & distinct terminology (with examples) at https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/Technical_documentation_templates_and_suggestions#Tips_for_writing_in_genres

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

In T234634#5566953, @TK-999 wrote:

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 ?

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.

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

In T234634#5571469, @Quiddity wrote:

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?

• Currently we just use these generic cleanup templates: https://www.mediawiki.org/wiki/Documentation/Style_guide/templates
• Perhaps we want to use some sort of scoring-system, like the Wikipedia's sometimes use "stub/start/c/b/a/good/featured" (quality) and "top/high/mid/low" (importance) type ratings?
• See also https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/Technical_documentation_prioritization

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

In T234634#5567164, @Aklapper wrote:

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

In T234634#5578955, @josephine_l wrote:

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?

In T234634#5580278, @apaskulin wrote:

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 :)

In T234634#5578955, @josephine_l wrote:

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!).

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.

@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.

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.

(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.

In T234634#5600957, @greg wrote:

(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.

In T234634#5601028, @bd808 wrote:

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.

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.

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.

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

@greg FYI. @apaskulin and I have also met to discuss the next steps with this.

I hadn't heard of CodeLabs before, but someone made a tutorial using it for git + gerrit (https://dev-codelabs.web.app/codelabs/getting-started-with-git-and-gerrit/index.html) and it could be interesting to explore that format for MediaWiki tutorials (how to modify page contents on display; how to read/write to the database, etc)