Re: Too many tools, was Things that used to be clear

[Phillip Hallam-Baker <[e-mail]>]

+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 <[e-mail]> wrote:

> On Jul 13, 2019, at 18:05, Phillip Hallam-Baker <[e-mail]>
> 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
>
>