On Thu, Sep 11, 2025 at 2:26 PM Nana Sakisaka <aroma.slope.seven@gmail.com> wrote:
I have professional skills on AsciiDoc and I actually plan to migrate the entire Spirit documentation to AsciiDoc. Although we haven't made a consensus on which framework to choose, I believe AsciiDoc is the best and I plan to submit PR.
Yes, and note the following: asciidoc: the name of the markdown format asciidoctor: the name of a tool which renders asciidoc antora: a publishing framework which renders multipage documentation sets, in asciidoc format Antora is from the same author as Asciidoctor and it uses the same markdown format. The difference is that regular asciidoctor usually leads to 1-page documentation such as: https://boost.org/libs/describe Whereas Antora is designed for multi-page output such as: https://www.boost.org/libs/url Given the size of the documentation of each of the libraries in Spirit I would advise Antora (which as I said, uses asciidoc markdownj).
I believe the actual problem is that almost every open source developers naturally has the instinct that the GitHub repository is the primary place for such technical discussion. I honestly think that every developer who is affected by the breaking changes on the **`develop`** branch should immediately subscribe to the repository and post a comment on the PR.
On the one hand, the specific technical aspects of the breakage of backward compatibility are probably best handled in the corresponding GitHub issue. However there are also social aspects that merit discussion and those are best placed on the list. Conversations on GitHub are not discoverable in the same way that posts to the mailing lists are discoverable via the archives. With the mailing list, every contributor also has the option for a locally searchable archive unlike GitHub issues.
Vinnie, IIRC you were one of the modern developers who disliked the mailing list interface, no? I personally never use email during my OSS work except for Boost. Don't you feel stressed by this interface?
I'm not personally opposed to the mailing list yet it does have disadvantages. Signing up is slow, the archive uses a completely different interface and if you subscribe after a discussion begins you don't have the context in your inbox. For example if you want to submit a review after the review period starts and you subscribe then, you do not have the original review email to reply to. Also I get the sense that mailing lists are declining in popularity with the hypothetical youthful contributors. On the other hand, the mailing list has distinct advantages. You can use one program to keep track of all your open source projects. You can control notification settings across your devices. You get a local archive and you can filter messages. It spans all development topics across all libraries.
I assume that's why you repeatedly promote Slack.
Slack is a completely different communication medium. It is real time discussion which is well-suited for collaboration. It is not so well suited for discussing topics which involve all Boost stakeholders. You can't practically search through old discussions. It is a different thing, yet it is also popular because of its immediacy. It also handles images and formatted text, so it is easier to share code snippets and links to offsite resources have embedded previews. Here, it has an advantage over the mailing list. You can also do a voice call and share screen at just the click of a button.
I don't like this email interface at all. I broke the silence after 10 years of subscription because Vinnie mentioned my name on the list. (No offense. I think it was the right timing.)
Well, you've been subscribed longer than me :) quite the lurk. How do you feel about a web-based front end to the mailing list instead of your email client? Something like this maybe: https://lists.boost.org/archives/list/boost@lists.boost.org/ Thanks