Page MenuHomePhabricator

Explore doc.wikimedia.org as a potential base to expand on as a single entry point for key technical documentation
Closed, ResolvedPublic

Description

One of the current WMF goals is to establish a single entry point for key technical documentation.

The site doc.wikimedia.org mostly hosts auto-generated docs thanks to CI.
The frontpage of doc.wikimedia.org however has seen some custom changes in the last 10 months (see changelog of YAML file defining its content; initiated in 07392c22 by @Krinkle, offering a clean and adaptive layout, sections with boxes (which include programming language information and further links).

To avoid reinventing wheels and https://xkcd.com/927/ , we should explore if doc.wikimedia.org could serve as a base to iterate on.

  • Cognitive: Would expanding that page / site try to cover too many use cases (scope becoming too broad) for a reader? (scope creep)
    • Potential target group overload: Current page seems great if you know what you need (reference), by technologies / tech areas, for non-newcomers. If it's "I want to do..." it feels harder (achieve/understand), by task orientation, also for newcomers (outreach). Would trying to cover different reader purposes (document types) be welcomed?
  • Social: Shared sense of 'ownership' / gatekeeping / page scope, as 'page maintainers'? Good or bad to have "more chefs in the kitchen"?
    • Would potentially removing some listed stuff be acceptable? (Scope; also different levels of depths covered in each section)
  • Technical: Would expanding the page / site be technically possible and feasible? Structure and organization tbd. Vague thoughts (not necessarily good ones):
    • Could the top bar be used for navigation, e.g. include three or five [sub]page "tabs"/links (each based on a YAML file), as the top level of documentation categorization?
    • Could there be indexing items per programming language, and then (separate step) allow (on-the-fly?) filtering the view per programming language?
    • Could the controlled vocabulary entries per YAML item be expanded, e.g. to add a document type and a non-displayed steward/maintainer entry?
    • Could there be 'indexing' items per programming language and document type, and then (separate step) allow (on-the-fly?) filtering the view via checkboxes per programming language and/or per document type (e.g. "show only api references")?
    • Could an item have more than one lang entry?
    • Would load significantly increase / performance decrease? (unlikely?)
    • Could the CSS for programming languages be adjusted to have each programming language have a specific background color?
    • Could there be a search function? (could be overhead)
    • Could the top bar have a logo (shared/DocHomePage.php; lib/wmui-page.css)

Event Timeline

Aklapper triaged this task as Medium priority.Feb 14 2021, 12:59 PM
Aklapper created this task.
Aklapper moved this task from Backlog to 2021-Q1 on the Wikimedia-Developer-Portal board.

Bryan, Krinkle (thanks both for your time again!) and I met a few days ago to discuss the bullet points above and sync on our understanding.

Summary: Once we have sorted out resourcing for implementing a developer portal in the next Financial Year, doc.wikimedia.org is an option to further explore.
doc.wikimedia.org would need some tweaks and changes if we used it as a base for a developer portal (how that would compare to other potential implementation alternatives is yet to be sorted out in a few months).