AsciiDoc WG, AsciiDoc Language project, and the AsciiDoc community at-large,
I want to begin by explaining what OpenDevise's role will be in this initiative moving forward. After turning over the AsciiDoc WG chair role to Amarantha, we're shifting our focus to exclusively working on the AsciiDoc Language project. We're not going to take on any other tasks unless there's no work in the AsciiDoc Language project that requires our immediate attention. The purpose of this pivot is to be able to dedicate all our available time to moving the AsciiDoc Language project forward.
That brings us to the state of the AsciiDoc Language project. Since the creation of the AsciiDoc Language project was approved, we've struggled to make progress. Part of that delay can be attributed to difficulties getting the infrastructure set up. But even after we made it over that stumbling block, the project still hasn't seen much activity (except for pending updates to the language guide). I think the problem lies in both its scope and the structure of the leadership. I'd like to propose some changes to the AsciiDoc Language project to address these problems.
First, I'd like to nominate Guillaume Grossetie to act as the lead of the TCK part of the project and I'd like to assume the lead role of the spec part of the project. This will essentially give the AsciiDoc Language project two leads, but in a way that splits the responsibilities along a logical line so they can proceed in parallel. I'd also propose setting up a new repository to host and develop the TCK. That will allow the TCK to have its own milestone releases.
Second, I'd like to tighten the scope of the AsciiDoc Language project. It's clear to me that we're trying to take on too much at once. The AsciiDoc Language project should be razor-focused on the syntax, grammar, and parsing of the AsciiDoc Language. The only time the spec should mention output formats is to stipulate mandatory behaviors and integrations to support the content written in the document (e.g., syntax highlighting, STEM, etc). You can find the revised scope I'm proposing in the following issue in the asciidoc-lang project:
https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/issues/11.
Here's the revised plan for the project. It's tough to put specific dates on these items since there's still a lot to figure out, so I've marked them by quarter:
* share revised scope and new plan with the AsciiDoc WG (Oct 17 meeting)
* sync changes to the language guide from the initial contribution repository with the asciidoc-lang project repository (Q4)
* switch the source of the AsciiDoc Language guide (
https://docs.asciidoctor.org/asciidoc/latest/) to the upstream asciidoc-lang project (Q4)
* revise the process documents in the asciidoc-lang repository; remove anything not mentioned in the EFSP as currently defined (Q4)
* create an initial draft outline (i.e., high-level document structure) for the spec document (chapters and major themes) (Q4)
* provide feedback on TCK process / framework to get it moving (Q4)
* write an introduction / overview of the spec (What is AsciiDoc? About this document etc) (Q4)
* define preliminary / primitives and terminology (Q4 and ongoing)
* release first milestone of spec and TCK (or split into independent releases) (Q4)
* iterate on each chapter, releasing milestone after each (Q1 2023 and beyond)
I'm going to move as quickly as possible through these tasks up to the point where we have the initial draft outline. That's when I think we can start getting other writers involved with preparing the first milestone and beyond.
With these proposed changes, I'm confident we'll start to see immediate and steady progress on the AsciiDoc Language project and for participation in the project to grow. OpenDevise is reentering with a renewed focus and, in doing so, will steer clear of all other matters. We believe that this approach best utilizes our abilities and ensures that the primary objective of this initiative gets the attention it requires.
Best Regards,
-Dan
