Skip to content

Latest commit

 

History

History
77 lines (68 loc) · 4.69 KB

spec-tooling-guides.md

File metadata and controls

77 lines (68 loc) · 4.69 KB

DIF Specification Tooling Guides

Brand Guidelines Style Guide Working Group Lifecycle Work Item Lifecycle Github Donation Spec Tooling Guides Code of Conduct

DIF Knowledgebase for members, work items, and communications:

DIF recommends picking the spec-authoring tool most appropriate to the target audience and/or target Standards Development Organization (SDO). If your work item can come to a consensus up front about an SDO that it wants to target from the beginning, we advise the group to work within the format and tooling preferences of that SDO from the beginning. If no clear SDO can be agreed to upfront, or if a "DIF-terminal" specification is consensual from the beginning, we recommend SpecUp, a markdown-based tool maintained as a standing work item of the DIF technical steering committee.

The tools recommended by DIF are:

  1. SpecUp is a lightweight markdown generator similar to Jekyll, which is itself hosted and maintained as a standing DIF work item.
    • Work items intending to use Spec-up for their deliverables should request a "spec-up repo" from DIF at time of beginning work, i.e., a repo generated from the SpecUp repo template
  2. BikeShed is a general-purposes specification authoring tool with many features and settings, which may be a bit overwhelming for more junior/inexperienced audiences.
  3. ReSpec is the native specification tool of the W3C community, is a more bibliographically-oriented tool. Feature requests or questions about advanced configuration topics and customization should be directed to the [specification producers mailing list][https://lists.w3.org/Archives/Public/spec-prod/] and community group, which governs both respec and spec prod/echidna, the github action that powers it.
  4. XML2RFC is the preferred spec-authoring tool for IETF RFCs, but may require a bit of XML familiarity; the dockerized version, markdown2rfc, also contains the similar go-based tool, mmark, can be a more user-friendly experience.
    • Unless editors have prior experience with IETF spec tooling, we recommend work items intended as IETF internet drafts start work in a repository generated from the DIF fork of the internet-draft-template by Martin Thomson (a long-time IETF WG chair). It contains a dockerized version of markdown2rfc and automations for github that can be customized (documentation forthcoming). If for IETF acceptance reasons (or for other SDO-target reasons), a repo needs to be housed outside the DIF github org, it should be clearly stated in the README.md and CONTRIBUTING.md at time of inception that the repo contains an ongoing DIF work item that only accepts substantial contributions from DIF members in the WG. Tagging the repo with the appropriate tag (i.e. wg-cc) helps them be displayed on the WG's webpage on the DIF website and generally assists discoverability & visibility.
    • Note: It is also possible to generate IETF RFCs from markdown files using BikeShed in situations where user-friendlier tools lack flexibility.

Educational materials

SpecUp education materials are forthcoming. In the meantime, see github issues at the repo. There is also a video of tool creator Daniel Buchner giving a quick tour of key features.

ReSpec educational materials are also forthcoming. In the meantime, see the overview and video created by the W3C CCG-- note that there are also instructions on how to generate ReSpec from markdown via github automation.

Acknowledgements for Specs

As DIF is a place for collaboration, acknowledging work funded or done by others is a gesture to recognize the efforts behind ratified work items. Consider creating a section for acknowledgments and recognize specific grants, people, or organizations whose work was invaluable for the delivered work item.