search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 807 forks source link

Zulip migration #980

Closed abelsromero closed 3 years ago

abelsromero commented 3 years ago

To improve communication, organization and community engagement we want to migrate to Zulip as chat/online communication tool over gitter. The main advantatges that Zulip offers are:

abelsromero commented 3 years ago

As analisy I have created a test organization: https://a2f4ec92e27d40129bd5711761bf949d.zulipchat.com with some preliminary configurations.

Here is the information I have collected so far:

Hosting options Cloud hosting with all features for OpenSource projects for free: https://zulip.com/for/open-source/ You can request sponsorship during organization creation, in an organization's billing page, or contact us at sales@zulip.com.

Plans details: https://zulip.com/plans/

Authorization of new users

Administration We can have multiple “owners” and “Administrators” if needed (https://zulip.com/help/roles-and-permissions).

Limitations/Concerns

abelsromero commented 3 years ago

Here are the tasks I have identified we need to do once the organization is created:

  1. Initial setup under Settings > Organization

  2. Setup default streams (channels), those that users see when joining

    #asciidoctor
#asciidoctor/asciidoctorj
#asciidoctor/asciidoctor.js
#antora/users (Gitter) — Community support for Antora users.
#antora/dev (Gitter) — Discussions involving the development of Antora.

@mojavelinux About streams, seeing how "asciidoctor" gets most of activity, maybe we can just create one "#asciidoctor" and see how it goes. What channels do you think we should have by default?

  1. Update links to gitter in repos GHub/GLab/twitter/etc https://gitlab.com/antora/antora README ???
abelsromero commented 3 years ago

@mojavelinux another topic to agree if we should create 1 single organitzation to hold both asciidoctor and antora streams (channel in Zulip terms). I think it makes sense to have just asciidoctor. In case in the future we want to migrate to "asciidoc", we can change the name requesting support, only downside is that users will need to relogin again (https://zulip.com/help/change-organization-url).

mojavelinux commented 3 years ago

Thank you for doing this research and analysis. This is extremely helpful information! I'm definitely comfortable making this switch.

We should not group Asciidoctor and Antora as these are separate projects and communities (even though they share a very close relationship). For now, we should focus on Asciidoctor. Antora will build on the work we do here.

The same would go for AsciiDoc. That's a separate community (managed by the AsciiDoc WG). Despite having an extremely close relationship to Asciidoctor, it's still not the same.

So the community should just be "asciidoctor" (and titled as "Asciidoctor").

I think we should make this a gradual migration. We get it set up, tell people to join, and eventually the Gitter channels will be depleted. We can keep them available for searching the archives, but no new conversations should occur there once we are all set up on Zulip. (While a lot of great things have been said in the channels on Gitter, I just don't think it's worth the effort and aggravation to try to migrate the data).

What I do want to avoid in Zulip is the impression that the Asciidoctor channels are split. That's the feeling I get in Gitter. I think the problem is that it's not clear when to discuss in asciidoctor/asciidoctor and when to move to ".js" or "j". Instead, I think we should have a main room, then we can have streams for each project. You would enter a stream when you're discussing something specific to that project (how to use AsciidoctorJ with OSGI, for example). But everyone gets to share the main room.

The question, of course, is what to call that main room. This is always tricky. If you think it should just be the top level, "#asciidoctor", I could get behind that. Then the Asciidoctor Ruby project would be "#asciidoctor/asciidoctor-core" (or just "#asciidoctor/core"). The other streams already make sense.

Cloud hosting with all features for OpenSource projects for free: zulip.com/for/open-source

I would really like to be on a non-free subscription. First, we want to support Zulip. Second, we have the money to do so. And third, we always get bitten by free services. If we are a paying "customer", then we reduce the risk of getting burned. I can assist with the invoicing, which we will do through OpenCollective.

Restrict Stream creation to only “admins”

This one is tricky. Some people have told me that allowing users to create streams often gives them the space to have constructive interactions. On the other hand, it could get unwieldy. Perhaps we can start with the restriction, but open it up later once we get familiar with it and see how it goes.

Set 10 minutes after posting (same as default for editing)

Set this to the maximum time that is allowed, perhaps capping it at 1 hour if there is no limit.

Logo-fill-color.svg converted to png seems to work fine

Please use this script to create the PNG: https://github.com/asciidoctor/brand/blob/master/export-to-png.sh Use the maximum PNG size it will allow so we get the best resolution.

We can have multiple “owners” and “Administrators” if needed

Let's make sure we have several admins to start with. My initial nominations are you, Guillaume, Alexander, Sarah, and myself. We can then add more people who want to step into this role.

mojavelinux commented 3 years ago

@abelsromero @Mogztter @djencks @brunchboy @graphitefriction I'm ready to proceed. I think we can tweak the settings once we are set up. Sarah and help with the graphics when we get to that point.

@abelsromero can you manage setting up the "asciidoctor" organization on Zulip and adding the administrators? Can you also let Zulip know that we want to be on the Standard plan? Sarah and I will handle the billing part. Just let me know when it's time to do that.

brunchboy commented 3 years ago

🎉

You’re not even going to request a sponsored (free) plan as an open-source effort? That’s generous! 😄

mojavelinux commented 3 years ago

I think it's a matter of means. Since we know that paying for the Standard plan helps support the Zulip project, and Asciidoctor has the means to do so, we want to provide that support. And since not all Open Source projects can do that, we can perhaps allow Zulip to continue to assist those projects.

mojavelinux commented 3 years ago

I've studied the Zulip documentation a bit more closely, and I see that choosing the right streams is essential. So I want to give it a bit more thought. Since we are going in as the Asciidoctor organization, we know that we can assume the context is asciidoctor. I like the idea that we can namespace streams to help funnel the traffic. I also like the idea in @brunchboy's community of having a "pub" for non-tech banter and an "introduce yourself" for newcomers.

Here's my proposed list. Feel free to revise.

#main
#announce
#help
#asciidoctorj
#asciidoctorj/help
#asciidoctor.js
#asciidoctor.js/help
#docker
#docker/help
#introduce yourself
#pub

What I'm not sure about is whether to make a distinction between #main and #core (aka #asciidoctor-ruby). That might just get confusing. On the other hand, maybe part of the problem is that we don't have separation between Asciidoctor as a whole and users of the Ruby gem(s).

I also wonder if we should have the typical users/dev split, or whether that is too fine-grained.

Thoughts?

mojavelinux commented 3 years ago

If we have multiple organizations, you'll have to open each organization in its own tab (unlike Gitter). However, if you use the desktop app (which is available for Linux), all the organizations you've connected to show up in the same interface.

mojavelinux commented 3 years ago

Btw, I'm thinking the "help" streams we might create later. I'm just showing where they might go. Though, perhaps, instead of help, we could make "dev". So we assume users is the default (which is actually what people do anyway), but then have special areas for "dev".

abelsromero commented 3 years ago

More than the channels list I am concerned the billing process may bite us in the future. According to the page, users subscribed to more than 1 channel are billed (https://zulip.com/plans/, "How are guest users billed? "), regardless of activity.

Even assuming not everyone will migrate, let's say 40 now, and then people migrated overtime with a 5% user increase every month, we'll be in 4K total for 2021, and 8,3k for 2022.

image

Looking into 2022 may be speculative, but still 4k for 2021 is no joke imho.

PS: never though I'd be pasting spreedsheets in here

mojavelinux commented 3 years ago

Wow, I missed the "per user per month" subtext. I thought it was per organization. You are right, that is costly. Perhaps we can negotiate with Zulip some sort of a reasonable cost for an open source project, because as you said we have a growing number of users (many of whom may not even be active). We could managed $15/month as a flat rate ($180 per year). That is a pretty standard rate for online services. (Just consider Netflix, which is pushing out blockbuster entertainment at around that price).

ggrossetie commented 3 years ago

I think it's too fined grained considering that discussions will be organized by topics:

#announce
#users
#meet & greet

I regrouped #pub and #introduce yourself in #meet & greet. Again, each discussion will be in a topic, so someone saying "Hi, it's Guillaume" will be in a "👋 Guillaume" topic and a banter will be in an appropriate topic :laughing:

I feel like users don't necessarily associate the underlying technology. They are Asciidoctor users and when they post a question they don't necessarily know if it's related to Docker or Asciidoctor.js or whatever. Having said that, maybe after after some initial discussion it will be become clear that a particular question/topic is related to Docker or Asciidoctor.js but then we can update the topic name to make it clear.

For reference, it's also possible to move a topic from one stream to another but I think we will spend valuable time moving topics around if we create too many streams (or ask users to move their topic to the appropriate stream).

Arguably, we could add a #dev in the future if we feel like we need a dedicated stream to talk about project management and development.

Maybe in the future it will become clear that we need more streams but I would suggest that we start with only a handful.

brunchboy commented 3 years ago

Yes, I started with just two streams, for quite unrelated projects, and have grown to three. Things like the “pub” and “help” are topics under the main streams. I think it’d be good to start with few streams, let topics form under them naturally, perhaps planting seeds for some, and add new streams when there seems to be a reason to keep some things more distinct.

mojavelinux commented 3 years ago

Things like the “pub” and “help” are topics under the main streams.

OMG. You're right. Sorry for misrepresenting that configuration.

brunchboy commented 3 years ago

No worries! It’s initially hard to parse how real and useful topics can be after suffering under Gitter for so long. 😆

mojavelinux commented 3 years ago

@Mogztter @brunchboy Thanks for that feedback. I can now see how overusing streams can split the conversation too much and step on the toes of topics.

I'd like to propose a slightly revised version of the streams that @Mogztter suggested:

#announce
#users
#socialize
#development

Automated messages should only go into #announce and #development. I find it very discouraging when a bot is littering the users channel with announcements and status updates.

I think all the meet and greet / pub stuff should just go under the socialize banner. The intent is very clear and we can allow all sorts of topics to come in under it.

Where I am torn is whether to make AsciidoctorJ and Asciidoctor.js topics or streams. People who have issues with AsciidoctorJ are usually talking about very different and specific things than the Ruby users. Topics like OSGI and classpath errors and Maven and Gradle integration come up. I think having those discussion in the main channel leaves the wrong impression. Same goes for Asciidoctor.js, which deals browser-related loading and Opal. It can get noisy for those who don't understand that environment. So I'm really leaning towards making them streams.

The problem with just using a topic is then it becomes a monolith since it can't have other topics under it. So the stream gives those communities space to grow.

mojavelinux commented 3 years ago

One idea for a topic under #users that could help reduce the noise in the channel is "help me get started" (though we could also just consider that to be "help"). When people first start, they usually hit some sort of problem. So this would be the topic where we get people over that first bump. It also allows other people who are just getting started to find information related to problems other people have encountered.

brunchboy commented 3 years ago

That reasoning makes a lot of sense to me, and I think that is a good argument for keeping the Java and JavaScript worlds separate streams if you do think people will want topics in them. Also, with respect to the bots, as long as they stick to particular topics, users can mute those topics: https://zulip.com/help/mute-a-topic

mojavelinux commented 3 years ago

Arguably, we could add a #dev in the future if we feel like we need a dedicated stream to talk about project management and development.

The reason I feel this is important to have is because when we discuss things like changing CI servers, I think it really shuts out users who are trying to learn. We really shouldn't step on their space.

djencks commented 3 years ago

I like the idea of having both #users and #development (although the names aren't parallel constructions) but... in Antora, dev is unused. Are we sure #dev would actually be used? At Apache new projects are strongly advised to start with one mailing list and only split user/dev when the traffic becomes too large.

mojavelinux commented 3 years ago

with respect to the bots, as long as they stick to particular topics, users can mute those topics: zulip.com/help/mute-a-topic

Good to know!

Btw, the documentation for Zulip is pretty awesome.

mojavelinux commented 3 years ago

in Antora, dev is unused.

It's in a lapse right now, but when we need it, it does get used heavily. And I think Asciidoctor has even more of this because we are managing a lot more infrastructure.

ggrossetie commented 3 years ago

I'd like to propose a slightly revised version of the streams that @Mogztter suggested:

👍

Where I am torn is whether to make AsciidoctorJ and Asciidoctor.js topics or streams.

We can create as many topics as necessary related to AsciidoctorJ or Asciidoctor.js.

People who have issues with AsciidoctorJ are usually talking about very different and specific things than the Ruby users. Topics like OSGI and classpath errors and Maven and Gradle integration come up. I think having those discussion in the main channel leaves the wrong impression. Same goes for Asciidoctor.js, which deals browser-related loading and Opal. It can get noisy for those who don't understand that environment. So I'm really leaning towards making them streams. The problem with just using a topic is then it becomes a monolith since it can't have other topics under it. So the stream gives those communities space to grow.

Is it really about programming language? maybe the dichotomy is between developers and writers/users? What about technical discussions (multiple topics) about the Ruby implementation in #users?

How do you feel about a #tech stream to keep developer discussions out of #users?

One idea for a topic under #users that could help reduce the noise in the channel is "help me get started" (though we could also just consider that to be "help").

I don't think a topic should aggregate multiple help requests (or more broadly multiple discussions). In my option, it will be hard to follow which requests are answered, which are not... who is talking to who... much like what we have today with Gitter.

djencks commented 3 years ago

Is Antora going to be part of this migration?

mojavelinux commented 3 years ago

Is Antora going to be part of this migration?

Nope. Antora is a separate project and will have its own organization. I mentioned the reasoning in an earlier reply in this thread.

mojavelinux commented 3 years ago

We can create as many topics as necessary related to AsciidoctorJ or Asciidoctor.js.

I know, but that still feels very klugy.

Is it really about programming language?

I wouldn't say programming language, I would say platform. And I do think that the needs on the different platforms are very different. Just take extensions. The way they are written and loaded in AsciidoctorJ does not apply in any way to Ruby extensions. And the group of users is typically very different too. Most of the time, you're using one or the other.

What about technical discussions (multiple topics) about the Ruby implementation in #users?

I don't see where #dev is a problem. Though I'm open to names like #developers (though that could be too amorphous) or perhaps even #project dev. Perhaps the clearer the better.

I don't think a topic should aggregate multiple help requests (or more broadly multiple discussions).

This is where experience will guide us. I'm just speculating how it might be used at this point, so perhaps we just need to tweak as we go.

mojavelinux commented 3 years ago

BTW, I just discovered you can use emoji in stream names!

ggrossetie commented 3 years ago

I don't see where #dev is a problem. Though I'm open to names like #developers (though that could be too amorphous) or perhaps even #project dev. Perhaps the clearer the better.

You mean a new stream named #dev in addition to #development?

To clarify, I don't understand why asking code related questions in #users (for instance, how do I retrieve the subtitle from the AST in a Tree processor or how do I create custom converter or how to integrate Asciidoctor in a Rake task...) is "OK" but asking Asciidoctor.js or AsciidoctorJ related questions is not (and should be asked in a specific stream)?

BTW, I just discovered you can use emoji in stream names!

Yay! 🎉 🎉 🎉

So... 💎 Ruby question ☕ Java question 🐳 Docker question 🌐 Browser extension question

Not sure which emoji we should use for JavaScript 😅

Maybe we are putting too much thoughts and we should adjust along the way... As @brunchboy said

I think it’d be good to start with few streams, let topics form under them naturally, perhaps planting seeds for some, and add new streams when there seems to be a reason to keep some things more distinct.

mojavelinux commented 3 years ago

You mean a new stream named #dev in addition to #development?

No, we only need one. We just need to decide what to call it. @djencks mentioned the name wasn't parallel, so I was trying to come up with one that was, but also clear that regular users that need help won't be interested in it. We tend to get users coming into dev in Antora, so the name might be the problem.

I don't understand why asking code related questions in #users (for instance, how do I retrieve the subtitle from the AST in a Tree processor or how do I create custom converter or how to integrate Asciidoctor in a Rake task...) is "OK" but asking Asciidoctor.js or AsciidoctorJ related questions is not (and should be asked in a specific stream)?

What I'm trying to avoid is conversation tripping over each other. I realize topics help a lot with this. And perhaps they already solve the issue. But given that Asciidoctor, AsciidoctorJ, and Asciidoctor.js all have very different usage patterns, it feels like trying to group them into a single channel is just going to lead to a lot of confusion. (It's quite possible I'm wrong about this, so this is really just a worry I have).

One of the problems with my proposal is the mixed use of the term "users". So perhaps these three streams should instead be:

#users
#asciidoctorj/users
#asciidoctor.js/users

Another possibility is to swap the order:

#users
#users/asciidoctorj
#users/asciidoctor.js

That might work because it funnels the conversations from macro to fine-grained. Instead of making AsciidoctorJ and Asciidoctor.js parallel hierarchies, it just makes them a refinement on users (and we could imagine the same for dev, if necessary).

Naming is so hard.

mojavelinux commented 3 years ago

I was looking over some of the option for the organization. We may want to consider them to make the community more engaged:

...then there is the world of bots, but we don't need to decide on that right away.

mojavelinux commented 3 years ago

I wonder if each message should be required to have a topic. @brunchboy can you offer any insight here? What setting did you pick?

abelsromero commented 3 years ago

@mojavelinux Back in the day I created the "test" org https://a2f4ec92e27d40129bd5711761bf949d.zulipchat.com/login/, if you login with GitHub I can make you admin and you can play

mojavelinux commented 3 years ago

Don't worry, I already have an instance I'm using. I set one up for OpenDevise. So I can see all the back office settings now.

mojavelinux commented 3 years ago

We will want to set up a public archive so people can browse without joining. There's a tool for it and setting it up on GitHub Actions seems rather straightforward. https://github.com/zulip/zulip-archive (It could be really useful for pointing people to solutions we previously discussed).

mojavelinux commented 3 years ago

I wish Zulip would let you have a different full name and mention name. For the profile, you want to see the full name so you can tell one person from another, but it's kind of weird that you see the full name when you @ mention someone. Perhaps we can use a custom field for the full name, and then use the actual full name field for how you want to be mentioned. So for me, I might enter "mojavelinux" in the normal Full name field, and "Dan Allen" in our custom Full name field. (Though it's not enforcing that either be unique, which is kind of strange).

brunchboy commented 3 years ago

I wonder if each message should be required to have a topic. @brunchboy can you offer any insight here? What setting did you pick?

I have not turned on that requirement. I haven’t seen anyone try to post a message without a topic yet, so I don’t really understand the impact.

brunchboy commented 3 years ago

I was looking over some of the option for the organization. We may want to consider them to make the community more engaged:

This was interesting. Here are what I have so far, but I am expecting these to evolve.

  • Invitations required? No. Members and admins can send invitations. (They aren't required, so the invitation is more of a nudge)

Definitely same here, and I plan to keep it this way.

  • Authentication methods: <= This is a tough one. Should we allow GitHub, GitLab, Google, and SAML, or just restrict it to email-based? GitHub seems like an obvious choice. I'm not as keen on Google, and SAML just seems obtuse. Perhaps Email and GitHub to start?

This one I just left them all on, I didn’t really care much. I’d be surprised if anyone used SAML, it’s such an effort, but I don’t see that being a problem either. Why does having Google available bother you? I did disallow the use of disposable email addresses in the Organization permissions section, however they determine that.

Ooh, some neat ideas here I will shamelessly steal. This was an area I planned to get to when I had a little more free time. 😄

  • Default streams: Definitely #users at a minimum (So that everyone who joins is in a stream by default).

I’m wondering if I should rename my #general stream #users. It seems more meaningful, and better captures the way I think of it.

  • Allow message editing? Up to 1 hour after posting (this can be whatever we want, and it does track edit history)
  • Allow message deleting? Up to 1 hour after posting (this can be whatever we want)

You were more generous than me here, I left mine at the defaults, but I cranked them up a little now too.

  • Default language for code blocks: text (I hate when it highlights when you don't enter a language, because it usually gets it wrong)

In my case, Clojure is an easy choice; 99.44% of the time it’s me doing the code blocks, and showing how to use Clojure code to customize an integration. For my users, if they even know how to quote code blocks, the same.

  • Add linkifier Perhaps the format should be <project-name>#<issue-id> (e.g., asciidoctor#1001)

That is what I did, although I also added the longer-format one where you specify the org.

  • Who can access user email addresses? Thoughts? By default, you see the email address on a user's profile

I didn’t adjust this one originally but the first user who joined me on the stream suggested hiding them because some people might not want everyone to be able to email them outside of Zulip, so I now only allow admins to see them.

...then there is the world of bots, but we don't need to decide on that right away.

Indeed! I set up a bot for only one project so far, and probably want to tweak its settings before adding other bots for other streams.

brunchboy commented 3 years ago

Aww! The list is only single-select, not multi-select. So you can only pick one favorite project. I may bail on that idea after all. I wonder if they already have an issue open about that? They don’t, so I am asking about the possibility in their own #issues stream on their (very busy) community Zulip chat.

ggrossetie commented 3 years ago

I can get behind this proposal:

#users
#users/asciidoctorj
#users/asciidoctor.js

When in doubt, I think people will ask in #users which is fine and then we have the option to move topics to the appropriate stream. Personally, I don't mind mixing technical and non-technical topics in #users/asciidoctor.js. Unlike Gitter, people can actually hide/ignore a topic if they are not interested. BUT, a technical topic can contain valuable information even for a non-technical person and vice-versa so I would prefer to keep them in the same stream.

mojavelinux commented 3 years ago

I wonder if each message should be required to have a topic.

I have not turned on that requirement. I haven’t seen anyone try to post a message without a topic yet, so I don’t really understand the impact.

Without it, the topic becomes "(no topic)", so it actually looks quite strange. I think we should require it. Surely anyone typing something can summarize what they are talking about in a few words or less (like with emails). If that becomes a problem, we can always lift the requirement.

mojavelinux commented 3 years ago

Why does having Google available bother you?

It doesn't bother me. I just think it would send the wrong impression that we are requiring a Google account (which, trust me, has come up in the past). But honestly, I guess I don't understand well enough the relationship between the SSO and the account to really know what to do one way or another. It's more about making the sign up screen look a bit simpler.

mojavelinux commented 3 years ago

In my case, Clojure is an easy choice; 99.44% of the time it’s me doing the code blocks, and showing how to use Clojure code to customize an integration. For my users, if they even know how to quote code blocks, the same.

:100: In our case, the default is likely AsciiDoc or a shell command, which is always screws up. I would prefer those to be text. I'm glad Zulip has this option because every community is different!

mojavelinux commented 3 years ago

That is what I did, although I also added the longer-format one where you specify the org.

I think we should support both. If the / is present, it will match a different rule. Without one, it assumes "asciidoctor" is the org. Thanks for giving me that idea.

mojavelinux commented 3 years ago

When in doubt, I think people will ask in #users which is fine and then we have the option to move topics to the appropriate stream.

Sounds good to me! And it seems easy enough to drop if it becomes too split.

I don't mind mixing technical and non-technical topics in #users/asciidoctor.js.

For me, it's not really about technical or non-technical. Surely, the users channel can be both. What I don't think we should discuss in users is stuff that is not at all relevant to users, like which CI server we are using, problems with auth or bots for repositories, and that sort of stuff. But releases would be users because users care about releases. So I think it's a use your best judgement kind of thing.

(When we switched from Travis to GitHub Actions, I think we shut out a lot of people asking questions in the channel for a time, so I think that is what we should remember).

brunchboy commented 3 years ago

Without it, the topic becomes "(no topic)", so it actually looks quite strange. I think we should require it. Surely anyone typing something can summarize what they are talking about in a few words or less (like with emails). If that becomes a problem, we can always lift the requirement.

That makes sense! If I start seeing that happen, I may turn it on too. In the mean time, I will rely on the fact that I can assign a topic later myself if I want to. https://zulip.com/help/change-the-topic-of-a-message

mojavelinux commented 3 years ago

@abelsromero When you get a chance, can you create the asciidoctor organization and add me as an Owner? Then I can start helping to plug in these settings. We should start with it being invitation only while we are configuring it, then we will open the doors to the public.

abelsromero commented 3 years ago

I am going to ping again later (10h from now).

abelsromero commented 3 years ago
mojavelinux commented 3 years ago

Thanks @abelsromero! I've configured the settings and set up the stream names as we discussed.

There are a few things left to finalize: