Asciidoctor: An active open-source community building software to share knowledge
Started in 2012, the Asciidoctor community develops an open-source text processor for parsing AsciiDoc content, enriching it, and converting it to formats such as HTML 5, DocBook, PDF, and many others.
For years, the project struggled to find a way to bring the community together in one place. Thanks to recommendations from leaders at other open-source communities, the Asciidoctor project leads decided to give Zulip a try to see if it could solve those challenges. “Moving to Zulip transformed our dialogue, making it organized, inclusive, and thoughtful in a way it never was before,” says project lead Dan Allen. “We finally had a home base. Zulip has been a game changer for our community.”
“Zulip has been a game changer for our community.”
— Project lead Dan Allen
A decade-long search for a communication platform to bring the community together
“In the early days, we started out only communicating using the GitHub issue tracker,” Dan Allen recalls, “but we could see that it wasn’t going to scale. It doesn’t provide a channel for general dialogue.” The project tried IRC, but it was unapproachable for newcomers and lacked modern chat and moderation features. Asciidoctor set up a discussion list, but that wasn’t a good fit either. Contacting hundreds of people over email to ask a simple question always felt inappropriate, and the lack of real-time interaction ended up making conversations take longer.
Looking for a web-based chat solution, Asciidoctor tapped into Gitter in 2014. “Gitter certainly looks modern and approachable. However, we quickly learned that the single, running thread of the channel was both chaotic and stressful,” Dan says. And the platform had mostly stagnated.
Many users in the community pleaded for threads, but Gitter’s threading feature (finally added in 2020), only made the situation more problematic for the community. “Threads buried the replies. You had to either navigate to threads using notifications, or scroll back multiple pages to find the little ‘see replies’ link and rediscover the thread. It was just so tedious,” Dan recalls.
“The conversations in Gitter were becoming more about Gitter and its limitations and less about the project itself.”
— Project lead Dan Allen
While Gitter allows users to create new rooms, what the project really needed was a single community space with “socially distanced” conversations going on. They needed a new model. And that’s exactly what they found in Zulip.
Asciidoctor moves to Zulip: “All the anxiety and stress was gone”
With the community continuing to grow, Dan and fellow maintainers decided it was time to seek out a better solution. Drawing on advice from leaders of other open-source communities, the project decided to give Zulip a try in early 2021.
Zulip’s streams and topics model immediately clicked. “Streams partition the community without making it feel divided. When someone has a question, they can find the most relevant stream and either make a new topic or contribute to an existing one.” This paradigm was a game-changer. “Literally the day we moved to Zulip, all the anxiety and stress of keeping up with the discourse was gone,” Dan says.
With Zulip, Dan has developed a comfortable workflow for catching up on conversations after being away. “When I start my day, I open up the Recent topics page and work through the topics that have activity on-by-one,” Dan describes. More casual community participants can skim the topic list to find interesting discussions, and mark topics they don’t care about as read with a single click.
Powerful moderation tools help keep conversations on track
Zulip’s topic model helps discussions stay focused. “Zulip starts the conversation out on the right foot by giving it its own space as a topic,” Dan explains. “As a result, conversations don’t have to be branched from an arbitrary spot, and the discussion is much more likely to stay focused and succinct.”
“Zulip starts the conversation out on the right foot by giving it its own space as a topic.”
— Project lead Dan Allen
If a topic starts in the wrong place or veers off course, Zulip’s moderation tools make it easy to fix. Community moderators can keep the dialogue organized by reclassifying topics and posts without disrupting the ongoing conversation. “If someone accidentally posts to the wrong stream or topic, Zulip allows me to move those messages around so they land in the right spot,” Dan says. “Moving messages also sends a subtle hint to the person posting about where to post the next time. And I can use topic references to link to the new topic location, or to a related topic. That’s incredibly powerful,” Dan says.
The ability to mark topics as resolved helps moderators see at a glance which topics require their attention. “Many topics reach a logical conclusion when the initial question has been answered, and the initial poster will typically express that they’re satisfied. At that point, one of us marks the topic as resolved,” Dan explains. “When I’m looking for topics that need my attention, I can focus on the ones that aren’t yet resolved and try to help get them to that state.” Later on, community members can use resolved topics as a reference source.
Zulip enables organized, inclusive and thoughtful discussion
After a successful launch of the Asciidoctor community on Zulip, Asciidoctor’s sibling project Antora adopted it as well. For both projects, using Zulip has been night and day compared to other platforms. “I can manage hundreds of participants across two communities extremely efficiently, and I don’t feel stressed,” says Dan. “I used it for my company chat as well. Zulip is calm and organized. I can immediately see what people are asking and jump to respond when I need to.”
“I can manage hundreds of participants across two communities extremely efficiently.”
— Project lead Dan Allen
The sense of space created by Zulip’s topic model has made the community more inclusive. “Using Zulip gives space to a much broader range of voices. We’re seeing people participating who never participated before,” Dan says. “People who are less extroverted, who don’t speak English natively, or just can’t type as quickly now all have a chance to be part of the dialogue. Zulip offers a more manageable pace.”
“We’re seeing people participating who never participated before.”
— Project lead Dan Allen
Even the tone of conversation has shifted, becoming more respectful and thoughtful. “People are more relaxed. They can think and take their time to reply. Topics give people space. People don’t feel like they are trying to talk over someone else. That means you can have more constructive dialogue because the volume level is lower,” says Dan. At the same time, Zulip enables lightweight interactions. “Often times, I participate just using emoji. I must use the 👍 and 🎉 reactions dozens of times a day,” Dan says.
Streams have also helped the community get to know one another better. “When we created the instance, we set up a #social stream. We seeded it with the topic ‘introduce yourself’, and new members took full advantage of it,” Dan says. The social stream has brought a more personal touch to the community. “In real life, no one just walks in and starts asking questions out of the blue,” Dan points out. “In the social stream, we’ve talked about non-technical topics like TV series, screen setups, and holiday wishes just to get to know the people behind the screen name and enrich each other’s lives in other ways. What we learned? Everyone enjoys a lot of British TV. ;)”
Zulip makes information easy to find
As a community grows, its conversation history becomes a trove of reference information. However, this history provides value only if the information is findable. “Once a conversation went out of view in Gitter, it was essentially lost,” Dan says. “The search was global across the whole Gitter instance, and it only returned excerpts with no sense of context. It was often faster to just scroll through the history in an attempt to try to find where the conversation happened than it was to search.”
In contrast, Zulip offers a faceted search that lets you find past discussions with pinpoint accuracy. “You can narrow the search to a stream or topic (with autocomplete!),” Dan points out. The results are presented with topic headings, making it easier to see whether the message is relevant. “You can click the topic to see the message in context,” Dan says. “It’s not only a great way to search, but it’s a great way to catch up on messages too. You can also search for all messages you sent, which turns out to be a great navigation tool and a memory saver!”
“Zulip is the heart of our community”
Dan is passionate about supporting Zulip’s development. “If we don’t sponsor the open source projects we love, we’ll have no one else to blame if we live in a world of proprietary software,” Dan says. “We truly feel heard by Zulip developers when we provide feedback. We also love that Zulip is truly open source, not open core like some alternatives. And we very much appreciate Zulip supporting open source by hosting our Zulip instances.”
“Zulip is the heart of our community, and nearly everyone who participates absolutely loves it,” Dan says. “It really does provide everything we need to manage the discourse, including topic-based threads, mentions, faceted search, moderation controls, polls, and emoji.” Speaking on behalf of the Asciidoctor and Antora projects, Dan wholeheartedly recommends that other communities give it a try. “Many communities have been strained to the limits during the pandemic,” says Dan. “Zulip brings health back to these communities.”
Check out our guide on using Zulip for open source, and learn how Zulip helps communities scale!