zulip/templates/zerver/for/asciidoctor-case-study.md

## Asciidoctor: An active open-source community building software to share knowledge

Started in 2012, the [Asciidoctor](https://asciidoctor.org) community develops
an [open-source](https://github.com/asciidoctor) 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](https://github.com/mojavelinux). “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](/why-zulip/) 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](/help/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](/help/reading-strategies) 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](/help/moderating-open-organizations) 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](/help/move-content-to-another-stream) 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](/help/link-to-a-message-or-conversation#link-to-a-stream-or-topic-within-zulip)
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](/help/resolve-a-topic) 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-makes-information-easy-to-find).


## Zulip enables organized, inclusive and thoughtful discussion

After a successful launch of the Asciidoctor community on Zulip, Asciidoctor’s
sibling project [Antora](https://antora.org) 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](/help/emoji-reactions). 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](/help/search-for-messages) 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](https://blog.zulip.com/2021/04/28/why-zulip-is-on-github-sponsors/), 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](/features) 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](/for/open-source), and
learn how Zulip [helps communities scale](/for/communities)!