Slides now at https://commons.wikimedia.org/wiki/File:A_central_place_to_link_key_technical_documents_(wmhack_2021).pdf

Copying the Etherpad notes from https://etherpad.wikimedia.org/p/WMHACK21_Central_place_to_link_key_tech_docs :

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

Speaker: Andre

Link to presentation:
https://commons.wikimedia.org/wiki/File:A_central_place_to_link_key_technical_documents_(wmhack_2021).pdf

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! https://www.mediawiki.org/wiki/Developer_Advocacy/Developer_Portal
• 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

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