Dear TC members,
On Wed, Apr 23, 2025, at 15:23, Laurie Tyzenhaus via OASIS wrote:
> Morning/afternoon/evening,
>
> The format selection should be driven by which is easier to convert to html.
>
> >To clarify, the TC members will collectively decide on the editors and the format. While we typically see one
>
> >to four editors for a work product, there is no limit. Regarding format, docx and markdown are
> >the most popular choices, with a growing trend towards markdown.
>
> A couple of years ago the SEI CERT migrated a project (SSVS) from GitHub to html. Creating links to other portions of the SSVC protocol was a pain. This is how it looks today... from this github.com/CERTCC/SSVC to certcc.github.io/SSVC
>
> Best,
>
> Laurie Tyzenhaus
>
> Software Engineering Institute
> CERT Coordination Center [...]
my obvious recommendation is to go with markdown, notably
GitHub flavored markdown, as it nicely renders directly
in the browser for technical as well as non-technical
readers, which makes the collaboration on issues and
change sets very inclusive and smooth.
Also, worth considering is managing the source markdown
in smaller files and assemble a single file markdown
delivery item from these in parallel to a dedicated
HTMNL delivery item.
I know that some TCs use issues and the implicit markdown
to HTML rendering capability per GitHub to shape proposals
that then go nearly 1 to 1 into the prose (per a subsequent
pull request).
Personally I like the space arrangement löayout that
markdown text already offers in "source" format.
As hinted above, in some TCs, we split up the prose documents
in the "source" folders into manageable snippets (cutting along
sections or subsections depending on the substance therein) and
than create the delivery items in GitHub-optimized markdown
as well as single file self-sufficient HTML documents with the
eidotiral revision pull requests.
This way, we minimize conflicts across pull requests, and
everyone can decide when inspecting the new documents, if
they like a differnce view on the snippets, or on the single
file markdown, or download and read the HTML file.
In these TCs, I know of: CSAF, OData, SARIF, as examples, we use
pandoc and some simple tools (like OASIS admins do when publishing
our workproducts) together with plain stylesheets.
In my experience, also the management of links from writing
to validating is easy to do with markdown and the resulting HTML.
Another advantage in my little corner of editorial life
is, that we often have data models or parts thereof, as well
as examples embedded in the prose to relate the reader to
important points.
Using markdown, we can extract these snippets, make minor
corrections by reverting changes made to account for paged media
and general readability / focus (the width of lines and the
reduced vertical space e.g. becoming invalid JSON) to derive
separate code snippets we can validate and readers can use as
they are for a start. But, that may not be relevant for DPS
work products.
Last but not least, Microsoft Word's zipfiles that constitute
a document are not a good match to the GitHub workflows
as we cannot merge differences but can only replace one
file with another, as git cannot merge binary files.
Distributed editing of and commenting on such binary formats
requires dedicated web platforms like Google Docs
Microsoft's One Drive or the IEEE imeet platform to name some.
All these platforms have in my experience difficulties to
offer a useful commenting and discussion arena, as they are
centered around the one big document. In contrrast, GitHub
and other such platforms offer issues (to discuss parts)
as well as pull requests (complete change sets) to spread
focus areas and then recombine again in an orderly traceable
way (resolution of issue and link to a merged change set i.e.
new document revision).
Also the HTML based linking across such areas in GitHub
helps to relate distinct parts to each other.
In the hope it helps: I am willing to support as an editor,
but if that is not needed, I am happy to actively review as
far as a native German can do so in English.
Sorry for the long sentences and unedited text and thanks
for reading this far. Wanted to share some practical
experiences of my OASIS standards editing since 2005 (when
GitHub was not available, three years to go).
All the best,
Stefan.
Original Message:
Sent: 4/23/2025 9:23:00 AM
From: Laurie Tyzenhaus
Subject: RE: OASIS Standard Template
Morning/afternoon/evening,
The format selection should be driven by which is easier to convert to html.
>To clarify, the TC members will collectively decide on the editors and the format. While we typically see one
>to four editors for a work product, there is no limit. Regarding format, docx and markdown are
>the most popular choices, with a growing trend towards markdown.
A couple of years ago the SEI CERT migrated a project (SSVS) from GitHub to html. Creating links to other portions of the SSVC protocol was a pain. This is how it looks today... from this https://github.com/CERTCC/SSVC to https://certcc.github.io/SSVC/
Best,
Laurie Tyzenhaus
Software Engineering Institute
CERT Coordination Center
Original Message:
Sent: 4/22/2025 1:43:00 PM
From: Kelly Cullinane
Subject: RE: OASIS Standard Template
Hi Roman,
That's an excellent question, and I apologize for the lack of clarity in my previous email.
To clarify, the TC members will collectively decide on the editors and the format. While we typically see one to four editors for a work product, there is no limit. Regarding format, docx and markdown are the most popular choices, with a growing trend towards markdown.
I recommend starting a discussion on these two points via the mailing list. If needed, you can address any remaining issues during your next meeting.
Once you've made these decisions, Kristina or one of the Chairs can open a ticket with me. I will then prepare your chosen template with the specifics of your TC. Following that, I will share the DPS-specific template, and it will be up to the editors to manage it from there.
Please don't hesitate to reach out if you have any more questions.
Thanks,
Kelly
Hi Kelly,Just to make sure I understand it correctly (still new to OASIS process) -Next steps for the TC are to decide on your spec editors and... -posted to the "OASIS Data Provenance Standard Technical Committee" community
Original Message:
Sent: 4/22/2025 1:27:00 PM
From: Roman Zhukov
Subject: RE: OASIS Standard Template
Hi Kelly,
Just to make sure I understand it correctly (still new to OASIS process) -
Next steps for the TC are to decide on your spec editors and determine what format you'd like to work in. Once you've done that, please complete this ticket to assign me the task of preparing your template.
Are those items to be completed by each member (bring the right people from their orgs) or by DPS TC collectively as a group?
Thanks.
--
Roman Zhukov
Principal Security Community Architect
Red Hat