Hi TOSCA-teers,
Briefly, as you know, the OASIS TOSCA system-of-record is the OASIS document site, email reflector, etc. Your chairs could also easily request a closed TC Github from OASIS staff that would limit contributions
to just TC members, as well.
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 said; in my personal experience, the collective cycles lost in the rathole of evaluation and discussion, consensus, then conversion and integration of the different tools in a fashion that is agreeable to
the consortium, the TC process (and the TC members themselves) are often never fully recovered.
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.
Regards,
Paul
From: tosca@lists.oasis-open.org <tosca@lists.oasis-open.org>
On Behalf Of Tal Liron
Sent: Sunday, February 23, 2020 5:49 PM
To: tosca@lists.oasis-open.org
Subject: [tosca] Using Markdown for collaborating on the TOSCA 2.0 spec
The learning curve was gentle and it seems to be able to do almost everything we need, though there are a few gotchas. (There are a lot of gotchas with the Word document, too, of course!)
For our Tuesday ad-hoc meeting I can do a demo of it. We can discuss all these details here or in the meeting:
-
It's entirely offline browser-based (and
open source), so anyone should be able to use it. Actually, the entire workspace is stored locally and can include many Markdown files organized in folders, including previous revisions and comments.
-
The commenting system is quite nice, in some ways easier to use than in Word. Any comment starts a "conversation" that anyone can respond to. It works by storing the conversation as extra data embedded in a comment within the Markdown file.
-
There's even a built-in diff tool, so if you look at one of the older revisions in the history and quickly see what has changed between that and the current revision.
-
It can synchronize your local workspace with Google Drive, Dropbox, CouchDB, and GitHub. I could not get it to work with my GitHub, but Google Drive seemed extremely easy to use, and it depends on Google Drive permissions, so it's easy to allow anyone to view
but only grant some people an edit permission. All the files sit in the drive and are pretty much standard Markdown, so that they can be downloaded, rendered into HTML/PDF/Word, published on a web site, etc.
-
Converting the current spec to Markdown would be fairly easy. I simply opened the docx file in LibreOffice and copied-and-pasted into StackEdit. Much of the formatting was automatically converted to Markdown. Tables are a bit trickier, but also not hard to
manage. I converted Chapters 1 to 3 with little trouble.
-
Cross-reference links are a bit tricky. The best method I think is to create anchors using some kind of convention, e.g. "section-1.2.1.1". Of course if the sections are moved around the references would have to be updated. But, since these are simple text
files, it wouldn't be hard to create a custom tool (in Python?) to search-and-replace. (By the way, the Word doc right now has a few orphaned references. Our Python tool could find such orphans and warn us about them.)
-
Including images is on the one hand awkward, but on the other hand straightforward. You can use any image URL in Markdown, but that means we will need to serve them from somewhere. One possibility is to use our TC GitHub repos, which can be easily made to host
publicly (via GitHub Pages). If we can get StakEdit to work with GitHub then it would be especially easy.
|