AsciiDoc standardization, next steps

[Dan Allen]

Fellow AsciiDoc enthusiasts,

AsciiDoc has gained traction as a preferred choice for technical writing in IT, and we all want to see it continue to grow. As we've discussed previously, in order for that to happen at this point, we need a specification.

With that said, I'm kicking off the standardization effort for AsciiDoc using the Eclipse Foundation Specification Process (https://www.eclipse.org/projects/efsp/). I'm doing so on behalf of OpenDevise, who will serve as the Lead Organization. With Stuart's blessing, we've taken the first step of proposing to establish the AsciiDoc Working Group.

The AsciiDoc Working Group (WG) administers the overall effort and is responsible for initiating and steering the technical projects. The AsciiDoc WG will be governed by its charter (https://www.eclipse.org/org/workinggroups/asciidoc-charter.php). Note that the AsciiDoc WG is not officially established until its charter is ratified. The ones who vote to ratify the charter are the initial members who have signed the participant agreement for the WG (https://www.eclipse.org/org/workinggroups/wpga/asciidoc-working-group-participation-agreement.pdf). There's no fee for a committer member (i.e., individual) to sign this agreement (though there is an expected time commitment).

The primary goal the AsciiDoc WG will put forth is to graduate AsciiDoc from a de facto standard to an official specification with an open TCK and at least one compatible open source implementation. To achieve this goal, the AsciiDoc WG will originate the AsciiDoc specification project and ensure the specification is developed in accordance with the Eclipse Foundation Specification Process. The specification project will work to define the AsciiDoc language's terminology, syntax, ASG, document model, extension points, and so forth.

The AsciiDoc WG and its projects are open to everyone. You can become a member of the AsciiDoc WG, contribute to one of the projects, or just observe. If you're interested, please join the AsciiDoc WG mailing list (https://accounts.eclipse.org/mailing-list/asciidoc-wg). By participating, you can have a voice in how AsciiDoc is standardized and how it evolves.

Please direct all future discussions about the AsciiDoc standardization effort to the AsciiDoc WG mailing list.

Thanks and Best Regards,

-Dan

--

Dan Allen | @mojavelinux | https://twitter.com/mojavelinux

[Lex Trotman]

Unfortunately this process does not allow those of us who are
individuals to participate, all participation requires membership of
Eclipse, which is entirely organisation related, it has no individual
membership.

Lex

> --
> You received this message because you are subscribed to the Google Groups "asciidoc" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to asciidoc+u...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/asciidoc/CAKeHnO6V3VpRZt%2Bq-CJrzVB6zUtgmyuXMgag%3DP5WJQRaYtAhtw%40mail.gmail.com.

[Dan Allen]

Any individual can join the Eclipse Foundation and the AsciiDoc WG as a Committer Member. See https://www.eclipse.org/membership/become_a_member/membershipTypes.php#committer and https://www.eclipse.org/membership/become_a_member/committer.php You can also participate without being a member at all. Just join the mailing list(s).

-Dan

[Lex Trotman]

On Fri, 14 Feb 2020 at 14:55, Dan Allen <dan.j...@gmail.com> wrote:
>
> Any individual can join the Eclipse Foundation and the AsciiDoc WG as a Committer Member. See https://www.eclipse.org/membership/become_a_member/membershipTypes.php#committer and https://www.eclipse.org/membership/become_a_member/committer.php

A committer involves more than just participating in development of
the standard, it involves write access to the projects resources. So
individuals who wish to contribute to the standard development, and
have a vote in the process (which is not available to ML contributors)
must necessarily have access to the repositories. That sounds like a
risky approach. I'm sure everybody will work in the best will, but
accidents occur, and documentation experts are not necessarily code
repository experts. Also by Eclipse rules individuals cannot join as
a committer, they need to be invited after experience, but how is that
process to occur for document writers (as distinct from coders) who do
not have coding experience, or for that matter coders who have no
involvement in existing Eclipse infrastructure? IIUC in the past
Eclipse has mostly taken stewardship of existing projects and their
teams so this startup issue didn't occur.

This is where Eclipse hasn't yet developed the "standards" process
sufficiently IMO, its processes are all about software development.

When developing a standard the users should be a significant part of
the voting participants, not just the application developers. This
has been my experience in the aerospace arena, even though standards
there can be imposed by legislation, if user involvement is poor the
results are poor.

Requiring document writers to have write access to the standards
repository to participate therefore seems inappropriate and unlikely
to attract many. You have stated before that the process for the
standards development can be modified, so here is the opportunity to
see if Eclipse can accept individual standards participants without
them having write access to repositories.

Also just out of interest, how is it proposed that the "conforming
implementation" be developed?

> You can also participate without being a member at all. Just join the mailing list(s).

I already did, but kept this here in the interests of not making the
first thread on the list a negative sounding one :)

Cheers
Lex

>
> -Dan

>
> --
> You received this message because you are subscribed to the Google Groups "asciidoc" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to asciidoc+u...@googlegroups.com.

> To view this discussion on the web visit https://groups.google.com/d/msgid/asciidoc/CAKeHnO4-G6ThHQ3bL%3DSDDkePgsc1eXZbebdb_1rcniDRMJTrVQ%40mail.gmail.com.

[Dan Allen]

There's some language inherited from the Eclipse Development Process which doesn't yet map cleanly to the Specification Process, at least in this case. The prime example is the label "committer" for individual. We have to apply a connotation to it that's relevant for our scenario.

> Also by Eclipse rules individuals cannot join as a committer, they need to be invited after experience, but how is that process to occur for document writers (as distinct from coders) who do not have coding experience,

The way we intend to approach it is that a committer is someone who's been nominated by a member in some capacity, not necessarily in response to code contributions. When we're talking about language design, particularly a documentation language, code won't be the basis for merit so to speak. (And we don't want it to be). It will likely be content in written form. We can use the charter to clarify this situation, and duly recommend that it be clarified in the EFSP.

> or for that matter coders who have no involvement in existing Eclipse infrastructure?

No matter what infrastructure is used, someone will have to learn it their first time around. That we can't control. But Eclipse gives us tremendous leeway in what we can use. For example, we can use GitHub or GitLab for the projects (as long as they mirror it). And I'm certainly willing to help anyone who is having trouble.

> This is where Eclipse hasn't yet developed the "standards" process sufficiently IMO, its processes are all about software development.

It's undeniably an emerging process, but that's also what's so exciting about it. With just over a dozen working groups coming before us, we have an opportunity to influence how the process evolves. Eclipse may learn from the workings of our group as much as we learn from them. You don't get a lot of chances to do that. Eclipse has a long track record of openness, transparency, and inviting new ideas, so I'm confident the group will feel comfortable communicating its needs.

> You have stated before that the process for the standards development can be modified, so here is the opportunity to see if Eclipse can accept individual standards participants without them having write access to repositories.

Absolutely. And thus far they have been very receptive to our suggestions, so I have no reason to doubt that we can do it.

> Also just out of interest, how is it proposed that the "conforming implementation" be developed?

That will be one of the key tasks for the Working Group and Specification Process to figure out (though I do have some ideas in my head of how to do it that I'll be proposing). Suffice to say, there will be loads of discussion about it.

> I already did, but kept this here in the interests of not making the first thread on the list a negative sounding one

Thanks. And welcome!