W3C Credentials Community Group

Increasing trust on the Web, one spec at a time.

Next Meeting

Date:
Time: 12pm Boston
Voice:
    VoIP: sip:ccg@96.89.14.196
    US phone: +1.540.274.1034 x6306
    EU phone: +33.9.74.59.31.06 x6306
Chat: Web, IRC
Duration:60 minutes

Announcements
Connecting to the Calls
Mailing List
Meeting Minutes
W3C Community Page

View the Project on GitHub w3c-ccg/w3c-ccg.github.io

Creating Specs/Reports for W3C CCG Work Items

Table of Contents

Table of contents generated with markdown-toc

About

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.

Quick Start

If you already know what tool/method you want to use to write your specs/reports, get started:

Which Method Should I Use?

For additional rationale behind the above guidance, see Recommendation Details.

Respec

Markdown Conversion

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

Spec-Prod is a W3C-provided tool that converts the bikeshed (extension of markdown files – uses .bs file extension) file to html.

Get Started

To get started, use the markdown-to-spec template repo. Follow the simple README steps

Learn More about Bikeshed

Bikeshed instructions

ReSpec Github Pages

ReSpec github pages also allows you to:

It uses Github Pages site generation to convert to the ReSpec html.

Other

If you already have a google doc, you can convert it to markdown or respec (and subsequently use the above methods).

Docs to Markdown

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.

To use:

Addon menu

Doc 2 ReSpec Tool (Beta)

This is beta and not known to be tested in the CCG, but feel free to try it out:

Recommendation Details

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.