Re: Test the Web Forward Documentation Update

-public-testtwf

Hi James,

This is great and another step toward unifying things. Thanks for taking
this on.  I made a few inline comments on the PR for on the CSS stuff. For
the most part, it looks great.

Can you describe a little more how this will work between 2 repos? Is the
entire docs directory going to be a subrepo in testtwf-website?  Where
will the index.html be? There are a few other things that I donıt see
ported over - faqs.md, glossary.md, bugs.md, test-a11y.md (granted, this
isnıt linked from anywhere, but the accessibility folks were kind enough
to contribute this at one the past events and itıs probably still
valuable).

Besides the PR workflow that is well documented, should we add something
to CONTRIBUTING.md with some guidance on contributing to the docs? We
currently have a little blurb on on this here [1]. We also document Jekyll
setup and advise that changes be tested locally first [2].  That may be
overkill for making simple edits to content in markdown, but if something
significant changes in the docs that breaks formatting, does the change
have to get propagated through the build to catch it? Is the onus on the
reviewer for that?

Thanks,
-Rebecca


[1] 
https://github.com/w3c/testtwf-website/blob/gh-pages/CONTRIBUTING.md#docume
ntation-format
[2] 
https://github.com/w3c/testtwf-website/blob/gh-pages/CONTRIBUTING.md#build-
tool



On 9/2/14, 9:37 AM, "James Graham" <james@hoppipolla.co.uk> wrote:

>I have been working on an update for the testthewebforward.org
>documentation page. This update has several goals:
>
>* To bring the docs up to date
>
>* To remove low-value documentation and make it easier to find the
>relevant documentation when working with tests.
>
>* To make future maintenance of the documentation easier.
>
>I think that one of the key reasons documentation has got out of date
>with the code is that it is in a separate repository. This makes it
>harder to require documentation changes as part of fixing bugs or adding
>features to tools. Therefore as part of my change I have moved
>documentation out into submodules, notably into web-platform-tests.
>However github-pages alone aren't able to deal with this setup, and as a
>result I've configured a (functionally equivalent) build process using
>Travis; you push the source to one repository and it automatically
>rebuilds the docs and pushes to a second repository. This also
>eliminates the slightly funky use of orphan branches.
>
>My updated docs are at [1] and there is a pull request at [2]. Feedback
>would be welcome; it would be nice to deploy this in the near future
>(days rather than weeks) as web-platform-tests are going to be turned on
>for Mozilla's CI system very soon, and being able to point people to
>up-to-date documentation is always nice.
>
>[1] http://jgraham.github.io/
>[2] https://github.com/w3c/web-platform-tests/pull/1219
>

Received on Thursday, 4 September 2014 18:22:45 UTC