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

[Paul L. <paul.lipton@LIVE.COM>]

Tal,

 

You make some good points and I recognize the passion. More seriously, may I  assume that there are commands and specialized markup to learn? Presuming yes, then is there some sort of WYSIWYG mode that can generate tags for people who prefer that form of editing? Also, can it import a Word file into a specific section of the text and attempt to autogenerate tags so that contributions written in Word can be more easily integrated? Just curious.

 

If youâre interested in showing the tool to the TC, perhaps with some examples of from the standard, I could leave the Zoom open after the TC meeting of March 12^th ends, or perhaps after a later TC meeting for 30 minutes. No pressure. Just a thought.

 

Thanks for your interest.

 

Regards,

Paul

 

From: tosca@lists.oasis-open.org <tosca@lists.oasis-open.org> On Behalf Of Tal Liron
Sent: Monday, February 24, 2020 4:49 PM
To: Paul L. <paul.lipton@live.com>
Cc: tosca@lists.oasis-open.org
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.