[DevHub] WordPress – testable, interactive documentation proposal

From my conversation with @adamziel

Stale documentation is an issue. But what if CI would raise alarm bells every time a Pull Request “breaks” the documentation? Even better – what if the documentation pages were interactive (like this Tag Processor tutorial)? The documentation would never go stale again AND the developers would enjoy a much better learning experience!

Technically, there are two parts to it:

Automatically testing the documentation
Rendering interactive documentation in the browser

The only thing they have in common is a source material that has a code snippet, a recipe to run it, and an expected output. That’s also the most challenging part – figuring out how to write that document. Perhaps a markdown document with some custom syntax? For example:
Here's how you can add an alt="" attribute to an tag:

<runnable>
   <dependencies>
      <file source="wordpress" path="wp-includes/html/wp_html_text_span.php" />
      <file source="wordpress" path="wp-includes/html/wp_html_tag_processor.php" />
   </dependencies>
   <code lang="php">
      <?php
      $html = '<img src="/husky.jpg">';
      $p = new WP_HTML_Tag_Processor( $html );
      if ( $p->next_tag() ) {
          $p->set_attribute( 'alt', 'Husky in the snow' );
      }
      echo $p->get_updated_html();
   </code>
   <expected-output>
      <img alt="Husky in the snow" src="/husky.jpg">
   </expected-output>
</runnable>

It’s a bit xml-y but perhaps it would do.

The CI handler would load the dependencies, run the snippet, and raise alarm bells if any PR leads to a different-than-expected output. So it’s just like a unit test.

The browser documentation would render a small code editor with a “Run” button and a result preview.