This page provides instructions for creating specs or reports for your CCG work item. The W3C has a small set of requirements for how community groups publish their reports, which these methods help you comply with.
At the core, ReSpec widely used for generating W3C specs/reports with consistent structure (and look and feel). And while you don’t have to use ReSpec (or the methods listed below), these make it much easier to comply with W3C’s community report requirements, which are critical for patent licensing commitments (among other things).
At the same time, some CCG members find working with ReSpec – which is HTML with the ReSpec js script – a little difficult or tedious. For that reason, there are other tools to help with either the initial creation or ongoing conversion. This describes the options, how to pick one, and instructions for getting started with each.
If you already know what tool/method you want to use to write your specs/reports, get started:
For additional rationale behind the above guidance, see Recommendation Details.
There are 2 methods to accomplish this. Both allow you to edit markdown files and have the html/ReSpec generated for you on commit. You can also use the toolset on your local machine to preview the html conversion, but the automatic conversion makes it easier for the broadest set of contributors.
Spec-Prod is a W3C-provided tool that converts the bikeshed (extension of markdown files – uses .bs file extension) file to html.
ReSpec github pages also allows you to:
It uses Github Pages site generation to convert to the ReSpec html.
If you already have a google doc, you can convert it to markdown or respec (and subsequently use the above methods).
Docs to Markdown is a google doc addon that will convert to markdown for you. You’ll most likely need to cleanup the markdown output, but it’s a convenient way to get started.
This is beta and not known to be tested in the CCG, but feel free to try it out:
|Tool Type||Required knowledge||Advantages||Disadvantages|
|Respec||HTML||Close change tracking||May be difficult for non-technical users|
|Ongoing conversion from Markdown||Markdown||Ease of use||Moderate change tracking|
|Conversion from doc||–||Initial ease of use||Output more difficult to understand; not recommended for use with ongoing conversions|
Note that a big distinguishing characteristic is the ability to perform change tracking on the generated (html) document. This is essential for very detailed and/or technical specs with a lot of changes (for example the VC and DID specs) – both for contributor tracking and for compliance with patent licensing commitments.
Ongoing conversion from markdown may be a sweetspot for either less technical reports or ones that are not moving to a working group (for example, community group notes and other reports). With github commit actions, it’s possible to run conversion tools on commit, so that all you have to worry about is editing markdown files. Change tracking on the markdown file is easy, but may be a little more difficult on the .html file. At the same time, it’s possible to use such conversion tools for a while and switch to using respec directly as a work item gets more mature.
The last category, involving use of tools that convert from .doc formats to .html are appealing but largely experimental. For that reason, this path is largely untested.