+1
Most of the docs I have describing the Mesh have three separate sources:
Word
Visio
Visual Studio projects generating markdown files.
Generating documentation from the schema is obviously the thing to do. In fact it is the main reason I use schemas to parse JSON. Generating Word document format and converting to XML would be painful. Generating examples and reference sections in markdown is straightforward.
I use Word to edit most of the text and generate SVG figures using Visio. My mechanism for including SVG is not currently compliant. I actually encode the SVG as a DATA uri. This is because I am only going to write a tool to conform my SVG with the requirements for IETF when there is something to test against.
Getting the SVG workflow working is going to be interesting for folk because the IETF has very restrictive requirements and very few tools actually comply with them out of the box. My plan is to dump out the Viso files into SVGs using a tool that does the necessary processing to strip out all the stuff that the IETF tools don't grok. The problem here being that SVGs are used on the Web as separate files. When you embed them in another file as XML data, the rules change.
One point that I do think important here is that we should agree to standardize on the Github flavor of Markdown. That is not the one I am currently using but will move to it.
On Sat, Jul 13, 2019 at 12:51 PM Carsten Bormann <cabo@xxxxxxx> wrote:
On Jul 13, 2019, at 18:05, Phillip Hallam-Baker <phill@xxxxxxxxxxxxxxx> wrote:
>
> google docs format. Then people could collaboratively edit the same source
Our students tend to do that with markdown files via hackmd.io (or actually the local open-source instance of that we have at the university). But then they are CS people, who live and breathe that documentation is code.
And that may actually be the reason why we will need two different toolchains for the foreseeable future: people who come with a developer mindset tend to use developer workflows and developer tools (git, github, automation, CI, …). Some other people view document generation as word processing, and therefore gravitate to word processing tools. Some organizations are relatively homogeneous with respect to this split (e.g., ITU doesn’t have a lot of developer-minded people), so they can standardize on one of the sides (e.g., ITU on MS-Word).
The IETF mixes both developer-minded people and, for lack of a better word for the other category, engineers, so we’ll need both sides. If a development team for specific document is mixed between the two categories, there will be some mismatch, and that is the place where markdown can shine compared to, say, W3C’s respec.
Grüße, Carsten
