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 19, 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.

For each experiment we start to plan, we'll write a more detailed plan that explains the experiment and its component parts. When we come to work on an experiment, we'll write it up as an Epic with user stories in our sprints repo.

CURRENT EXPERIMENTS

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

FUTURE EXPERIMENTS

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/EXPERIMENTS/QUESTIONS

Content components

  • BCD rendering
  • Specification tables
  • Interactive examples
  • 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
  • Consolidate page types (e.g. less than 38?)
  • We use definition lists a lot. They don’t work in markdown. Can we use them, or should we simplify?
  • Inside each docset, what pages should we migrate over, if not 100% (WebAPI, we’re mainly looking at you here)
  • Measure how much the different content sets are edited in a certain time period — HTML, CSS, JS, etc., to see how much of a problem this is likely to be.
  • Breadth — we have 38 page types. So far, in the HTML experiment, we are only exploring about 3 or 4. What will the code and the contribution process look like when we have 20, or 30? Will this cause Stumptown to get too complex? We should explore creating some other diverse page type recipes and rendering them, to see what this looks like.

Page structural features

  • More complex sidebars (building on the simple sidebars in the HTML experiment)

L10n

  • Making L10n work (worth looking in to machine translations?)
  • L10n is not a part of the HTML experiment. Perhaps we should do this as a separate experiment?
  • A research spike on what pages we need to translate for a locale to be effective. E.g. reference pages probably don't need translations, but we should probably translate our guides and learning pages...having guidelines on this would make locale projects easier to justify.

General MDN platform features

  • We should research whether an existing product exists that we could use to serve the need Stumptown is aimed at
  • Logins
  • Customizations (e.g. learning pathway progress, as a simple example)
  • 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.

Editorial workflow

  • User testing for contribution workflow — we ought to do this as early as possible, to see what problems are perceived with the new system by our contributors.
  • Workflow for contributing, including preview
  • Workflow for reviewing contribution
    • Steve Jalim mentioned that something like wagtail-review might be suitable, but obviously this exact solution would only work if we used a CMS like Wagtail
  • Tool to autogenerate stumptown pages for Web API ref docs from webidl?
  • Revision history. What do we need here? Is there any reason we need to keep the old revision history from Kuma? Is it good enough to have a list of historical contrbutors?
Clone this wiki locally