Stumptown experiments

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

The failure case is pretty similar for all of these assumptions — these all represent essential features for Stumptown to support; if we can't do these, it won't be viable.

• 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 get simple sidebars to work
• We can support info boxes in HTML element recipes
• We can support HTML element pages
• We can support HTML form input element pages
• We can support landing pages
• We can support global attribute pages
• We can support guides
• We can render specification tables on Stumptown pages
• We can render live/interactive examples on Stumptown pages
• We can write a linter to validate the content of our pages
• We can render all of the above content types as HTML pages that could be published on MDN
• We can create a usable workflow for contributors to the HTML content (e.g. document editor/writers)

More details

• More detailed plan
• 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.