Re: Test the Web Forward Documentation Update

On 04/09/14 19:22, Rebecca Hauck wrote:
> -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.

Thanks for the feedback! I'll fix the issues that you identified.

> 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?

So, the idea is that the documentation itself lives in the repository
associated with the code it's documenting. For example the
testharness.js documentation is a set of markdown files in the
testharness.js repository, and the documentation about tests writing is
a set of markdown files in the web-platform-tests directory (this could
be further split between web-platform-tests and CSS). This is great
because it means that code and documentation are close together and in
particular one can easily require documentation changes as part of code
review, when appropriate.

Meanwhile all the structure of the site lives in testtwf-website. This
has the code repositories as submodules. All the pages that end up in
the final website are markdown files under docs/ like before, but many
of them are just simple wrappers that {% render_partial %} something in
a submodule under _resources/ (the limitations of the built-in include
system mean that render_partial is a plugin, which is why octopress
can't be used directly).

index.html therefore lives in testtwf-website, just like before.

This setup does create some weirdness; the markdown files in submodules
often contain relative links, or links to resources, that only work in
the context of the full site. It also means a little bit of indirection
the first time you want to find where the content of a page actually
lives (you can always just clone testtwf-website recursively and follow
the link in the top level file, so I don't think it's too bad). I think
those are acceptable tradeoffs.

> 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).

We had a conversation about faqs.md on irc and there was a feeling that
it didn't really contain much that counted as a FAQ, so I removed it.
Similarly glossary.md didn't seem to be pulling its weight in terms of
usefulness (either just defining really basic things, or having somewhat
circular definitions). It might make sense to bring them back in
revamped form, but I don't think we are missing much at the moment.

bugs.md is still there in the testtwf-website repo (it doesn't really
feel like documentation of web-platform-tests *themselves*). I didn't
even know that test-a11y.md existed, but I'll have a read through and
see where it should go.

> 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?

That documentation seems more or less correct, still (there's a Rakefile
now, which helps a little). Possibly in the future we could consider
teaching Travis to build PRs to check for syntax errors, although there
would be a danger in actually pushing them anywhere.

Received on Friday, 5 September 2014 14:29:20 UTC