Use Bikeshed for spec?

[apowers313]

At W3C they are using bikeshed for specs. So that a spec like this automatically ends up as formatted HTML that looks like this. They use Travis CI to automatically update the specs on every check-in for an always-live "editors draft".

I think that something like bikeshed would be a big help to this project. If you guys are interested, let me know and I can help set it up and take a first pass at converting the spec.

[darrelmiller]

Thanks for the pointer. If we decide to move to a standardized format we will definitely consider this, along with the very similar process that creates IETF compatible specs https://github.com/http2/http2-spec

However, at the moment, formatting the document is really not the biggest challenge that we are facing.

[apowers313]

FYI, one of the IETF editors I was talking to mentioned that they are moving away from their current format to create something more user friendly.

You sure you don't want some free labor to reformat the specs? :)

[adrianhopebailie]

You can generate RFC style specs from markdown. We do it for some of our specs in the Interledger project: https://github.com/interledger/rfcs/blob/master/0002-crypto-conditions/0002-crypto-conditions.md

[adrianhopebailie]

p.s. I think the ReSpec toolset used at W3C is easier than Bikeshed but that may just be personal experience

[apowers313]

Yea, we're using ReSpec at FIDO Alliance, but I've been told that they're deprecating that in favor of bikeshed.

[MikeRalphson]

p.s. I think the ReSpec toolset used at W3C is easier than Bikeshed but that may just be personal experience

@adrianhopebailie having looked at ReSpec, it seems a fair amount of work is required to remove W3C specific boilerplate, copyrights, logos etc. See https://github.com/w3c/respec/issues/950#issuecomment-255723249

An example of processing the existing markdown with bikeshed is here - though I would not personally recommend changing the source format of the OAS to use bikeshed, due to bikeshed's current incompatibility with either commonMark or GFM (tables etc). There are distinct advantages in having the spec in a format natively rendered by GitHub without a build step.

[apowers313]

Note that W3C uses TravisCI to build the spec on commit, which seems to work pretty well. Also, I just went through modifying bikeshed templates to change the branding and it wasn't that hard -- happy to put together a quick prototype for the OpenAPI specification if you're interested.

I'm not part of W3C or OpenAPI so I really don't have a dog in this race, but I have done a lot of standards in the past and I love OpenAPI so I'm just trying to help it be successful. One thing I would offer as food for thought is that half of the value of a standard is being able to cross-reference it from other standards -- I'm not sure how that would work with the current OpenAPI setup.

[MikeRalphson]

Closing in favour of #1564