Page MenuHomePhabricator

[Session] A central place to link key technical documents
Closed, ResolvedPublic


A short presentation on the problem, the work that has happened so far (e.g. themes we have identified), open discussion.


Username or display name (will be displayed publicly): User:AKlapper_WMF / Andre Klapper

Saturday, May 22, 18:00UTC

Categories/Tags/Keywords (up to 5):

Session type (select one):

  • Presentation (including Q/A) - 25 mins

Venue (select one):

  • I need a Jitsi room for the session

When are you available to have the session?
Any time.

Session Details

Short description of the session (~150 words):
A short status update on work so far and plans about a central place for technical contributors which would provide links to the most relevant technical documentation. Afterwards, discussion (how to organize and improve discoverability of our documentation).

Target audience:
New technical contributors, developers, technically interested people, anyone who wants or needs to find technical documentation

What will participants get out of this session? (~50 words)
An idea of the challenges to organize and find Wikimedia documentation (and hopefully a better Developer Portal based on participants' input). :)

Additional resources:

Other comments:
For a general open discussion about technical documentation, please refer to T281589: [Session] Technical Documentation Q&A instead.

Event Timeline

Hello @Aklapper and thanks a lot for proposing this session!

Feel free to have a look at the remaining free slots in the two hacking rooms in the schedule (times are presented in UTC/GMT), and please add your session directly in the schedule on wiki, in one of the two hacking rooms, before May 20th. If you have issues editing the wiki, we can also do it for you, feel free to ask for help.

As a speaker in a hacking room, you will use Jitsi, where you will be able to present, share your screen, and interact directly with the participants. The session will not be recorded.

If you have any questions, feel free to reach out to me. Thanks!

Copying the Etherpad notes from :

A central place to link key technical documents (25 min, presentation, Q&A)

Speaker: Andre

Link to presentation:

Notes from session:

  1. Presentation
  • Quotes from users on how confusing and distributed our technical docs are
  • Classic problem: Which link to give out to new contributors?
  • Tackling the docs issue: Sometimes call it "documentation odysee 2001", as #2001 is the inital ticket number for tech docs on Phabricator
  • Andre summaries the work done so far: State of docs? Developer Portals at other projects? Previous attempts within WM? Typical issues around tech docs (interviews with engineering teams, 12-13 teams; research onwiki etc.
  • created content/structure draft for single entry points - high level technical areas/use cases to link to the various key tech docs. Attempt is not to duplicate docs, but to funnel people to the right places
  • Feedback very wanted!
  • What's next:
    • Dev Portal - implementation, improving key docs
    • This is just a starting point, gives us a way to prioritise, develop a roadmap, go from "highest level" and step by step improve the different areas
  1. Discussion

Feedback wanted on the content draft:

  • really liked box approach. Maybe something more "tree like". Persona approach. I am "x", want to do "y".
  • the boxes do that a bit, but maybe having a even more lean "top layer"?
  • Question: Any case studies planned in the future?
  • Question: What about docs that are not in a good stage, would you link to it?
  • Most important thing is to cover the key use cases. Part of the work in the second half of this calendar year - identifying the gaps in the docs we want to link to, improving pages, re-structure etc.
  • Really great initiative, thank you for leading it. (+1)
  • I like the portal and what it's trying to achieve. The current layout looks good (in mobile too!). I just have one doubt. Would it be worth mentioning Hay's directory or something similar in the portal as it might help them find similar tools?
  • Yes, want to link to Toolhub, once it is deployed (is not yet in the draft, as still under development)