Page MenuHomePhabricator

Decide on most suitable underlying technical platform
Closed, ResolvedPublic


General thoughts:

  • We want well-curated content and want to keep hosted information intentionally "limited" to key documentation. (cf T290255: Workflow how to propose content changes)
  • Wikis have a focus on a low-threshold contribution workflow ("Edit" tab etc). Compared to our "normal" wikis' edit rates and content, we do not expect a high rate of changes over time.
  • We'd like to completely avoid vandalism if possible.
  • Curation on a wiki might be possible via pretty restrictive edit permissions (or in addition FlaggedRevs but see T185664 about its problems).
  • Seeing the API portal and its custom skin, I dare to say that making wikis look and behave like a mostly static site is not what wikis are designed for.
  • We ideally seek a sense of ownership for listed content. Seeing e.g. WRC at , I am not convinced with regard to curation and active maintenance of content there. (Plus things like T169790 haven't happened.)
  • Regarding well-curated content, we also want a certain level of standardization, machine-readability (see T276708: Define content storage format (levels, data structure, hierarchy, categorization, etc)), and translatability (not based on the Translate extension because T131516 is real, but preferably

All of this makes me believe that MediaWiki is not the most suitable platform for a rather static Developer Portal site (cf. e.g. T67074#687573).

Thus we should explore other FOSS options, which, as a side effect, might also lower long-term maintenance costs.
(This may influence T261509: Sort out navigation concept to some extent, as MediaWiki skins also inevitably would.)

Related Objects

Event Timeline

Aklapper created this task.
Aklapper raised the priority of this task from Low to Medium.Jul 27 2021, 4:46 PM
Aklapper raised the priority of this task from Medium to High.Aug 3 2021, 5:28 PM
Aklapper renamed this task from Sort out technical platform to Decide on most suitable underlying technical platform.Sep 15 2021, 5:44 PM
Aklapper updated the task description. (Show Details)
bd808 changed the status of subtask T294387: Create POC using mkdocs from Open to In Progress.Oct 26 2021, 8:22 PM
bd808 changed the status of subtask T294387: Create POC using mkdocs from In Progress to Stalled.Nov 3 2021, 8:47 PM

Resolving this task as its subtasks are closed. Quoting T294387#7550579, we plan to use mkdocs as the base technology for generating the static site.

While wiki-style editing can be great for ease of contribution, it would have added technical overhead of setting up another wiki (and a skin) and using a wiki as a static site instead of a wiki, plus we want an element of curation with an ability to limit content as we expect content to mostly remain unchanged with only occasional updates. Furthermore, for the process of proposing and accepting content changes, a Phabricator board and patch workflow looked more feasible than setting up something like ApprovedRevs or FlaggedRevs.

It might be too late now, but are you aware of the MintyDocs MediaWiki extension ( It's already in use for technical documentation at at least one company (Genesys), and, in conjunction with extensions like Cargo, Page Forms and Approved Revs, I think it provides all the structure, ownership, and control over content that is required. And, of course, it means you get to use MediaWiki. Granted, I'm the main author of all four of these extensions, so I may be biased.