We have some docs on the privacy side of things in README.prod.md's security model section.

Also, just documenting the existence of a lot of nice features like the ability to add custom emoji would be valuable.

I think a really valuable thing to document in this space would be the various effective workflows ways one can use Zulip to manage one's messages - seems like an area that could be useful to teach and would highlight features like narrowing, muting, unread counts, etc.

Relatedly, having advice on when you should split a stream into multiple streams, when you should use a new topic vs. replying to an existing one when sending a message, etc., would probably be useful. (Some of these things might belong as separate tickets).

#599 is also relevant.

@porterjamesj @niftynei @workmajj if you could speak to what, for instance, new Recurse Center people often find confusing about Zulip, and what y'all tell new Recursers in person, that would be really helpful here! I already know that, for instance, we tell people:

• that it's great that Zulip is threaded
• that you can subscribe or unsubscribe to whatever "streams" you're interested in
• that it's hard to discover a stream if you're not already on it (thus it's a good idea for realm admins to invite new users to lots of streams initially and encourage users to ruthlessly unsubscribe/mute as they like)

What else?

Some of this help should be in-app (maybe in the initial tutorial), some in emails sent to the user as or just after they start using Zulip, and some should be on the public web at Read the Docs or (maybe) zulip.org. Tim mentioned to me:

we should definitely think through which things we want to be on RTD vs. in-app. E.g. keyboard shortcuts are nice to have in-app. Though we can always think about ideas like having them present in both places, since keyboard shortcuts being in-app means they aren't accessible to Google. #776 adds a mechanism for rendering markdown in-app, so we could think about using that...

Quoting myself from a Zulip conversation: Just sort of thinking out loud, but there are folks who are very home-view-centric (especially folks with Zephyr background, but not exclusive to them) and people who are very narrow-centric. I'm in the latter camp, as I find the interleaved view a little overwhelming at times. It's a challenge for the app to accommodate every user's preferred way of looking at their message stream. There may be opportunities in the docs to help that, e.g. "How do you survive Zulip as a narrower?"

Hello! As someone who has never used Zulip before, here's what I would've found useful:

1. Comparisons against other popular similar systems (IRC, Slack, Matrix, etc)
2. Some more tips for interacting with 'streams' and 'topics', both mapping them to concepts elsewhere if they exists better as well as actual UX tips (like clicking a messages allows you to reply)
3. Quick way to test it out (rather than screenshots)

Copied from my comment on zulip : i'm not sure if its worth mentioning it here, but working with a bunch of Zephyr users, the workflows for our zulip match a lot of what the existing Zephyr users have. It might be useful to have something like this for new users: https://sipb.mit.edu/doc/zephyr/

Some of the things that happen often that new users have trouble understanding right away:

• When conversations branch, the topic name often has a ".d" appended to it. There are cases where some topics have ".d.d.d.d" appended when people are very distracted
• Some users miss that messages are editable or how do edit a message
• @messaging can be trickey at first (same with /me messages)

I just joined a Zulip instance for the first time today. It's somewhat overwhelming at first, but I'm slowly figuring out what's going on. The main confusion I had upon first loading the interface was that I don't know what "Home" means, since it appears to contain conversations from many different threads, none of which I clicked on, and similarly, the notifications that pop up in the corner seem unrelated to anything I've done yet.

There seems to be no obvious way to reply to this message:

I think I was "invited?" to a new topic by @brainwane mentioning me in it. I wasn't totally sure what happened, but the topic appeared greyed out until I clicked around some.

It's not clear to me how to find the full list of topics for a channel. I like that the topic list autocompletes when I start typing, but it would be nice if clicking the text box would also show me a full list of topics.

It took me longer than I would have liked to realize how to include a hyperlink in my post. I never would have known it was possible had I not seen other people type linked text in other channels. Looking under the A (Formatting) button was not the first place I thought, since formatting to me implies things like bold, italic, etc. If you look at the toolbar in this Github issues interface, it includes quote, code and link as separate from text formatting.

I just experienced Zulip today. On my first attempt I after I subscribed, I wasn't sure of the sub-channels(threads) and therefore created a new thread, 'intro' in Outreachy 2016-2017 by mistake. I think the introduction tutorial kind of prompts you to make a thread, give it a simple name and start off. Plus, once created, I could see no way of deleting the thread to rectify my mistake too.
On another note,, it would be more intuitive if you showed the text box to type (at the bottom of the page) at every channel instead of clicking on the 'new stream message'. Private messages could always be sent by maybe clicking on the person's handle name on the side, thereby ditching the 'new private message' at the bottom.

I'm a brand-new user, and stumbled over basic things trying to find my way around. Here's some of them:

When I first logged in, I was looking for a place to introduce myself while I wandered around. I had never heard of Zulip and only had a url that was recommended as a resource to learn more. I saw there was a list of streams and looked through them to see if one would be the right place. It wasn't clear that streams and topics within them are central to how messages are organized. Topics seemed to be like email subjects, which is close but not quite. There was a consolidated topic for that purpose, but replying to someone else's introductory email to make my own introduction isn't how I would commonly use a mailing list. After I created my post in the stream (but not the intended topic) someone invited me to a different, more specific stream to continue the conversation. I wasn't sure if I was supposed to have found that somehow, and that felt weird.

I tried searching for the subject of interest that brought me there, by typing into the search box at the top of the web app. My search returned no results despite the term existing in numerous locations (as I was informed later.) Since there was some text already in the search box (I had clicked on streams) I tried deleting that text and typing my search again. Still no results. Even now, if I search from an empty search field I only see two results (from messages posted some time later.)

I apparently missed the first login user tutorial, and I can't find a way to access it again. (Someone has already opened an issue for this.) I'm not sure if it was related to having first logged in using a private browsing window, or that I was distracted by other things.

I initially saw a banner at the top of the screen under the search box. I don't remember what it said, but I sure do remember that it was covering up something else I was trying to look at. I couldn't dismiss it because the close button was under other text in the right sidebar. This is likely because the text was larger than expected as it was rendered for the minimum font size (18 pt) I set in my browser. I can't reproduce this right now, but I may be able to after I set up my own server and create a new user.

I tried to find some in-app help, but I still don't know where to look. There is a menu item for "API documentation" but that isn't user documentation. There is another for "Search help", with a magnifying glass search icon, that I thought would be where I could search for relevant help topics. But instead it's a quick reference to searching for messages.

I'll try to test some of these more throughly once I set up my own server.

replying to someone else's introductory email to make my own introduction isn't how I would commonly use a mailing list.

Yeah, actually, I wouldn't recommend that in Zulip either, for the same reason as in email -- it makes it easy for threads to get lost. The Outreachy instructions page (which is where I imagine you got the confusion instruction) has been updated in a way that should hopefully help.

(BTW, thanks for all the other feedback!)

From conversation today:

question: Is there a way to see who is in a Stream? (especially when there's been no conversation in it)

answer: If you go to stream management (the gear in the upper right corner will give you that option), and then look at more details on a particular stream by clicking the arrow/chevron on the right, you'll see who else is in a stream.

(Although we may be reworking that UI.)

My understanding is that https://github.com/brannerchinese/zulip_user_documentation by @brannerchinese is partially meant to address this issue, and that Tim is working on making a PR for it.

The new /help directory (just merged to master via #2266) and @brannerchinese's work on content resolves the main issue here of not having a system for user documentation; I think we still need to do some follow-up work to take all the feedback in this thread is actually discussed in those docs, that they're linked somewhere, etc. So I'm not quite ready to close this issue, but I think we should extract the things in this issue into their own issues and close it.

Huge huge thanks to @brannerchinese for getting our user documentation started!

What features are we looking to document that don't have issues already created for them?

Dropping a note here (sorry not to answer @synicalsyntax's question) to offer a data point. I invited someone to chat.zulip.org using the "invite a user" functionality. The new user emailed me:

I've never used zulip, so I don't know how to contribute to the thread.
How do I add text? I've been clicking around the website and watching the thread grow, feeling... a bit like an ass honestly.

Once I @-mentioned them I think they were able to figure it out. I wonder whether our tutorial/tour intro needs a little more explicit signalling, pointing to https://chat.zulip.org/help and indicating:

If you click on a message, you'll see a reply box open up below.

Closing this; I think it remains a great source of feedback on things we can improve in the app's onboarding, but certainly the original issue of creating user documentation on our features is resolved by the /help/ site. I'm closing this.