- From: Manu Sporny <msporny@digitalbazaar.com>
- Date: Mon, 18 Apr 2022 10:28:13 -0400
- To: W3C Credentials CG <public-credentials@w3.org>
Hi all, Just a quick note to those authoring specifications that need diagrams (swim lane diagrams, process flow charts, class diagrams, customer journeys, etc.). One of the challenges of having diagrams in specifications is keeping them up to date as the specification changes. Another challenge is ensuring that the diagrams continue to be accessible. There are usually a fair number of diagrams in CCG use cases documents as well as specifications. There is a diagramming tool called mermaid.js[1], which let's you describe diagrams using text (similar to Markdown). The tool then takes the text and renders a visual representation of the diagram. I've put together a plugin for our specification authoring environment (ReSpec) that enables us to embed these text-based diagrams in our use case and specification documents. The result is a dynamically rendered diagram that is more easily kept up to date with the specification. In other words, you no longer need to use a separate image/diagram editing program to create diagrams for specifications (though, you still have that option if you want to go that route). The downside here is that you will need to learn mermaid's markup language[1], which is fairly easy to pick up. There is also a live editor[2] that helps you see what you've marked up. We've started playing around with this feature in the VC API specification: https://github.com/w3c-ccg/vc-api/pull/286#issue-1206470583 You can read more about how to use the plugin here: https://github.com/digitalbazaar/respec-mermaid#readme This is the first experimental release; expect bugs[3], please report them, and we'll fix them as soon as we can. -- manu [1] https://mermaid-js.github.io/ [2] https://mermaid.live/ [3] https://github.com/digitalbazaar/respec-mermaid/issues -- Manu Sporny - https://www.linkedin.com/in/manusporny/ Founder/CEO - Digital Bazaar, Inc. News: Digital Bazaar Announces New Case Studies (2021) https://www.digitalbazaar.com/
Received on Monday, 18 April 2022 14:28:29 UTC