Skip to content
This repository has been archived by the owner on Sep 7, 2021. It is now read-only.

Stumptown experiments

Jump to bottom
Chris Mills edited this page Sep 12, 2019 · 8 revisions

The idea here is to collect together a summary of the experiments we will carry out in the experimentation phase, to provide the features that Stumptown needs to be able to provide. These need to be as useful as possible — proving new things, not just doing more of what has already been proven.

This summary should hopefully let us know at a glance if we are missing anything.

HTML docs experiment

  • Owner: Will
  • Priority: High

Summary of experiment

  • Port the entire HTML documentation set into GitHub as structured content.
  • Build the content as a set of web pages and start serving them to MDN users.
  • Switch the contribution workflow for HTML from the Wiki into GitHub.

Assumptions tested

  • Markdown is a good enough format for our docs
  • PR review workload will be sustainable
  • Structured content offers advantages over just migrating to GitHub
  • We can keep structures simple enough
  • We can support other MDN features (simple sidebars, examples, landing pages)

More details

  • More detailed plan
  • “Stumptowning HTML” list of required features
  • User stories/Epic

More complex sidebars

  • Owner: ?
  • Priority: ?

Summary of experiment

Assumptions tested

  • We want to demonstrate that we can create a single extensible way of doing sidebars that works for all the areas of MDN, not 40 different macros to do essentially the same thing, like we have now.
    • If we fail: Stumptown would not be viable — we need a system to generate sidebars

More details

  • More detailed plan
  • User stories/Epic

Template

  • Owner: ?
  • Priority: ?

Summary of experiment

Assumptions tested

More details

  • More detailed plan
  • User stories/Epic

Raw list of features we need/experiments/questions

  • BCD rendering
  • Specification tables
  • Interactive examples
  • Making L10n work (worth looking in to machine translations?)
  • More complex sidebars (building on the simple sidebars in the HTML experiment)
  • Live examples (what about LA examples. Could we use Glitch?)
  • Get guides working
  • Get other types of page working (WebAPI and their foibles, like inheritance)
  • For WebAPI pages, figure out how to get mixins/inheritance working
  • Logins
  • Customizations (e.g. learning pathway progress, as a simple example)
  • Consolidate page types (e.g. less than 38?)
  • Macro massacre; find replacements for KS macros that we can’t kill
  • Timely BCD updates; Look into GitHub actions to automatically update BCD on Stumptown MDN
  • Feasibility of work to update KS machinery to serve HTML from GitHub, not DB.
  • Workflow for contributing, including preview
  • Workflow for reviewing contribution
  • Inside each docset, what pages should we migrate over, if not 100% (WebAPI, we’re mainly looking at you here)
  • We use definition lists a lot. They don’t work in markdown. Can we use them, or should we simplify?
  • Tool to autogenerate stumptown pages for Web API ref docs from webidl?
  • A research spike on what pages we need to translate for a locale to be effective. E.g. reference pages probably don't need trans;ations, but we should probably translate our guides and learning pages...having guidelines on this would make locale projects easier to justify.
Clone this wiki locally