Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [asciidoc-wg] Intro + feedback

Welcome Philippe!

We're thrilled to have the participation of seasoned AsciiDoc writers such as yourself. And thanks for sharing your handiwork!

It's absolutely essential that, throughout this process, we preserve the essence of what continues to attract writers to AsciiDoc. We can relate about being self-made tech writers. That's what brought Sarah and I to AsciiDoc as well. Although we don't use DocBook as much these days, it was a crucial factor in the beginning that allowed us to migrate our content to AsciiDoc (having that escape hatch available). DocBook has also had a lasting influence on the semantics of the language, so that fact can never be understated.

> is it too late to indicate which parts of the AsciiDoc format I'd like to see changed/improved?

Not too late at all. In fact, too early. We're just in the process of getting this Working Group formed (the administrative aspects). An early step in that process is to submit a proposal for the technical project (i.e., the specification). Once that proposal is approved and executed, that's when the real technical work begins. The spec will then continue evolve indefinitely after that with each version that is published.

It sounds like you'll want to join that project once it's launched. We'll announce it on this list.

> I'm not a fan of all the parts of the AsciiDoc format

That's to be expected. We wouldn't need a working group and specification process if AsciiDoc was perfect. (We'd just rubber-stamp it and call it a day, but doing so doesn't leave room for improvement). This working group is all about making AsciiDoc the best we can make it and figuring out the best path to get there. So the friction of wanting something better is what lights the embers.

Best Regards,

-Dan

On Thu, Mar 26, 2020 at 6:05 PM Philippe Proulx <eeppeliteloop@xxxxxxxxx> wrote:
Hello there!

I just subscribed to this mailing list.

I'm a part time, self-made tech writer for software projects. I use
AsciiDoc (the Python version, most of the time; not that I want this,
but I could elaborate on the motives) to write design documents,
format/language/protocol specifications, manual pages, as well as full
project documentation.

My usual workflow for everything that is public is to go from AsciiDoc
to DocBook, and then use my own processor to get from DocBook to HTML.

Some documentation projects I wrote in AsciiDoc and maintain:

* LTTng Documentation: <https://lttng.org/docs/>

* LTTng manual pages: <https://lttng.org/man/>

* Babeltrace manual pages: <https://babeltrace.org/>

* Common Trace Format 2 specification proposal:
  <https://diamon.org/ctf/files/CTF2-PROP-1.0.html>

As a writer of technical documentation, I'm a heavy unordered/ordered
list, description list, and table user. Being able to nest those,
although how to do so is not always straightforward, is one of the top
reasons I choose AsciiDoc.

I was about to give some more detailed feedback about the AsciiDoc(tor)
format, but I see Sarah White already wrote (10 March):

> I submitted the draft proposal for the AsciiDoc specification, TCK,
> and related artifacts to the EMO (Eclipse Management Organization) on
> Thursday (03/05).

My question is: is it too late to indicate which parts of the AsciiDoc
format I'd like to see changed/improved?

Thank you for your work. Although I'm not a fan of all the parts of the
AsciiDoc format, it has filled my needs pretty well for years with some
tweaks and hacks.

This mailing list made me discover Antora and I'm looking forward to
trying it as a replacement or complement of Jekyll.

Philippe Proulx
_______________________________________________
asciidoc-wg mailing list
asciidoc-wg@xxxxxxxxxxx
To unsubscribe from this list, visit https://www.eclipse.org/mailman/listinfo/asciidoc-wg


--
Dan Allen, Vice President | OpenDevise Inc.
Content ∙ Strategy ∙ Community
opendevise.com

Back to the top