Re: Moving docs in-repo

On 4/23/14, 7:49 AM, "James Graham" <james@hoppipolla.co.uk> wrote:

>At present there is a split in our documentation between several places;
>testtwf-website is supposed to be the authoritative source, but actually
>it's not that well maintained. I suspect this is at least partially
>because of the high overhead for contributing; in order to update the
>documentation for e.g. testharness.js, or the in-browser runner, to
>reflect a code change you would have to make a second PR in the
>testtwf-website repo and wait for another round of review. In practice
>this hasn't been happening, so we need to make things easier.
>
>I suggest we try to move the documentation as close to the code as
>possible (i.e. in the same repo) and make the website generating code do
>the work of pulling in the right files. An obvious way to structure this
>would be to add the projects requiring documentation as submodules of
>testtwf-website.

This makes a lot of sense for the documentation that is bound to code -
testharness.js, runner, etc.  I donıt have any big objections to the rest
of the docs being submoduled in WPT, but Iıd point out that doc
contributors should still preview their changes as theyıd appear on the
site before they submit the PR. This means that they should still have the
testtwf-website Jekyll environment to be able to preview locally since the
Jekyll build cans sometimes can break for silly reasons. The situation we
want to avoid is having a PR merged from WPT that has build errors (or
even cosmetic/formatting problems that pass the build) and having the site
be broken. What would be the best way to enable this workflow?

Received on Thursday, 24 April 2014 18:31:33 UTC