Re: [tosca] Using Markdown for collaborating on the TOSCA 2.0 spec

Subject: Re: [tosca] Using Markdown for collaborating on the TOSCA 2.0 spec

On Mon, Feb 24, 2020 at 2:13 PM Paul L. <paul.lipton@live.com> wrote:

Naturally, Technical contributions should ONLY come from OASIS TOSCA TC members who have the right to make that contribution. That does not preclude small groups of TC member collaborators working on specific tasks from working offline using tools like Google Docs, of course.

That is exactly what is being discussed: an offline tool to improve collaboration. The tool can export a very clean Word document (and a PDF, and an HTML page) that can become the statement of record. I am attaching an example of such an output.

For these reasons and more, there is a certain value in sticking with MS Word supported file formats, not least that MS Word is already understood and used for complex documents such as specifications (and even 1,000+ page novels) by millions of people around the world; also making it easy for newcomers to dive right in.

Text files, I would argue, are even more readily understood, and definitely easier to process by tooling.

Our situation is that we have just a handful of contributors working on one big, extremely unwieldy Word document. The process has not produced great results: the spec is riddled with errors and inconsistent formatting. This is a serious problem not just for the English text, but also for the embedded TOSCA and YAML code. The only way we can do quality control currently is by manually copying YAML back and forth to other tools. There are likely various reasons for all these problems, but I can say that from my perspective the huge Word document is a source of dread and an obstacle to improving TOSCA. I'm certain that working with text files will allow us to put together a much better final result.

Please also note that some of us work for open source companies (me!) and do not have access to Microsoft Word. And Word itself is not free: it is in fact quite expensive. The current process is immediately discriminatory.

tosca message