contributor docs: Reorganize contributor guide.

- Offer more hand-holding at the start.
- Clean up dev environment setup steps.
- Move joining CZO later in the process.
- Move feedback section to feature suggestions page.
- Drop other non-coding info, as it exists elsewhere.

CONTRIBUTING.md

@@ -1,130 +1,103 @@
 # Contributing guide
 
-Welcome to the Zulip community!
+Welcome! This is a step-by-step guide on how to get started contributing code to
+the [Zulip](https://zulip.com/) organized team chat [open-source
+project](https://github.com/zulip). Thousands of people use Zulip every day, and
+your work on Zulip will have a meaningful impact on their experience. We hope
+you'll join us!
 
-## Zulip development community
+To learn about ways to contribute without writing code, please see our
+suggestions for how you can [support the Zulip
+project](https://zulip.com/help/support-zulip-project).
 
-The primary communication forum for the Zulip community is the Zulip
+## Learning from the docs
-server hosted at [chat.zulip.org](https://chat.zulip.org/):
 
-- **Users** and **administrators** of Zulip organizations stop by to
+Zulip has a documentation-based approach to onboarding new contributors. As you
-  ask questions, offer feedback, and participate in product design
+are getting started, this page will be your go-to for figuring out what to do
-  discussions.
+next. You will also explore other guides, learning about how to put together
-- **Contributors to the project**, including the **core Zulip
+your first pull request, diving into [Zulip's
-  development team**, discuss ongoing and future projects, brainstorm
+subsystems](https://zulip.readthedocs.io/en/latest/subsystems/index.html), and
-  ideas, and generally help each other out.
+much more. We hope you'll find this process to be a great learning experience.
 
-Everyone is welcome to [sign up](https://chat.zulip.org/) and
+This page will guide you through the following steps:
-participate — we love hearing from our users! Public channels in the
-community receive thousands of messages a week. We recommend signing
-up using the special invite links for
-[users](https://chat.zulip.org/join/t5crtoe62bpcxyisiyglmtvb/),
-[self-hosters](https://chat.zulip.org/join/wnhv3jzm6afa4raenedanfno/)
-and
-[contributors](https://chat.zulip.org/join/npzwak7vpmaknrhxthna3c7p/)
-to get a curated list of initial channel subscriptions.
 
-To learn how to get started participating in the community, including [community
+1. [Getting started](#getting-started)
+1. [Finding an issue to work on](#finding-an-issue-to-work-on)
+1. [Getting help](#getting-help) as you work on your first pull request
+1. Learning [what makes a great Zulip contributor](#what-makes-a-great-zulip-contributor)
+1. [Submitting a pull request](#submitting-a-pull-request)
+1. [Going beyond the first issue](#beyond-the-first-issue)
+
+Any time you feel lost, come back to this guide. The information you need is
+likely somewhere on this page (perhaps in the list of [common
+questions](#common-questions)), or in one of the many references it points to.
+
+If you've done all you can with the documentation and are still feeling stuck,
+join the [Zulip development community](https://zulip.com/development-community/)
+to ask for help! Before you post, be sure to review [community
 norms](https://zulip.com/development-community/#community-norms) and [where to
-post](https://zulip.com/development-community/#where-do-i-send-my-message),
+post](https://zulip.com/development-community/#where-do-i-send-my-message) your
-check out our [Zulip development community
+question. The Zulip community is governed by a [code of
-guide](https://zulip.com/development-community/). The Zulip community is
-governed by a [code of
 conduct](https://zulip.readthedocs.io/en/latest/code-of-conduct.html).
 
-## Ways to contribute
+## Getting started
 
-To make a code or documentation contribution, read our
+### Learning how to use Git (the Zulip way)
-[step-by-step guide](#your-first-codebase-contribution) to getting
-started with the Zulip codebase. A small sample of the type of work that
-needs doing:
 
-- Bug squashing and feature development on our Python/Django
+Zulip uses GitHub for source control and code review, and becoming familiar with
-  [backend](https://github.com/zulip/zulip), web
+Git is essential for navigating and contributing to the Zulip codebase. [Our
-  [frontend](https://github.com/zulip/zulip),
+guide to Git](https://zulip.readthedocs.io/en/latest/git/index.html) will help
-  Flutter [mobile app](https://github.com/zulip/zulip-flutter) in beta,
+you get started even if you've never used Git before.
-  or Electron [desktop app](https://github.com/zulip/zulip-desktop).
-- Building out our
-  [Python API and bots](https://github.com/zulip/python-zulip-api) framework.
-- [Writing an integration](https://zulip.com/api/integrations-overview).
-- Improving our [user](https://zulip.com/help/) or
-  [developer](https://zulip.readthedocs.io/en/latest/) documentation.
-- [Reviewing code](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html)
-  and manually testing pull requests.
 
-**Non-code contributions**: Some of the most valuable ways to contribute
+If you're familiar with Git, you'll still want to take a look at [our
-don't require touching the codebase at all. For example, you can:
+Zulip-specific Git
+tools](https://zulip.readthedocs.io/en/latest/git/zulip-tools.html).
 
-- Report issues, including both [feature
+### Setting up your development environment and diving in
-  requests](https://zulip.readthedocs.io/en/latest/contributing/suggesting-features.html)
-  and [bug
-  reports](https://zulip.readthedocs.io/en/latest/contributing/reporting-bugs.html).
-- [Give feedback](#user-feedback) if you are evaluating or using Zulip.
-- [Participate
-  thoughtfully](https://zulip.readthedocs.io/en/latest/contributing/design-discussions.html)
-  in design discussions.
-- [Sponsor Zulip](https://github.com/sponsors/zulip) through the GitHub sponsors program.
-- [Translate](https://zulip.readthedocs.io/en/latest/translating/translating.html)
-  Zulip into your language.
-- [Stay connected](#stay-connected) with Zulip, and [help others
-  find us](#help-others-find-zulip).
 
-## Your first codebase contribution
+To get started contributing code to Zulip, you will need to set up the
+development environment for the Zulip codebase you want to work on. You'll then
+want to take some time to familiarize yourself with the code.
 
-This section has a step by step guide to starting as a Zulip codebase
+#### Server and web app
-contributor. It's long, but don't worry about doing all the steps perfectly;
-no one gets it right the first time, and there are a lot of people available
-to help.
 
-- First, make an account on the
+1. [Install the development
-  [Zulip community server](https://zulip.com/development-community/),
+   environment](https://zulip.readthedocs.io/en/latest/development/overview.html).
-  paying special attention to the
+1. Familiarize yourself with [using the development
-  [community norms](https://zulip.com/development-community/#community-norms).
+   environment](https://zulip.readthedocs.io/en/latest/development/using.html).
-  If you'd like, introduce yourself in
+1. Go through the [new application feature
-  [#new members](https://chat.zulip.org/#narrow/channel/95-new-members), using
+   tutorial](https://zulip.readthedocs.io/en/latest/tutorials/new-feature-tutorial.html)
-  your name as the topic. Bonus: tell us about your first impressions of
+   to get familiar with how the Zulip codebase is organized and how to find code
-  Zulip, and anything that felt confusing/broken or interesting/helpful as you
+   in it.
-  started using the product.
 
-- Read [What makes a great Zulip contributor](#what-makes-a-great-zulip-contributor).
+#### Flutter-based mobile app
 
-- Set up the development environment for the Zulip codebase you want
+1. Set up a development environment following the instructions in [the project
-  to work on, and start getting familiar with the code.
+   README](https://github.com/zulip/zulip-flutter).
-
+1. Start reading recent commits to see the code we're writing.
-  - For the server and web app:
-
-    - [Install the development environment](https://zulip.readthedocs.io/en/latest/development/overview.html),
-      getting help in
-      [#provision help](https://chat.zulip.org/#narrow/channel/21-provision-help)
-      if you run into any troubles.
-    - Familiarize yourself with [using the development environment](https://zulip.readthedocs.io/en/latest/development/using.html).
-    - Go through the [new application feature
-      tutorial](https://zulip.readthedocs.io/en/latest/tutorials/new-feature-tutorial.html) to get familiar with
-      how the Zulip codebase is organized and how to find code in it.
-
-  - For the upcoming Flutter-based mobile app:
-    - Set up a development environment following the instructions in
-      [the project README](https://github.com/zulip/zulip-flutter).
-    - Start reading recent commits to see the code we're writing.
    Use either a [graphical Git viewer][] like `gitk`, or `git log -p`
    with [the "secret" to reading its output][git-log-secret].
-    - Pick some of the code that appears in those Git commits and
+1. Pick some of the code that appears in those Git commits and that looks
-      that looks interesting. Use your IDE to visit that code
+   interesting. Use your IDE to visit that code and to navigate to related code,
-      and to navigate to related code, reading to see how it works
+   reading to see how it works and how the codebase is organized.
-      and how the codebase is organized.
-
-- Read the [Zulip guide to
-  Git](https://zulip.readthedocs.io/en/latest/git/index.html) if you
-  are unfamiliar with Git or Zulip's rebase-based Git workflow,
-  getting help in [#git
-  help](https://chat.zulip.org/#narrow/channel/44-git-help) if you run
-  into any troubles. Even Git experts should read the [Zulip-specific
-  Git tools
-  page](https://zulip.readthedocs.io/en/latest/git/zulip-tools.html).
 
 [graphical Git viewer]: https://zulip.readthedocs.io/en/latest/git/setup.html#get-a-graphical-client
 [git-log-secret]: https://github.com/zulip/zulip-mobile/blob/main/docs/howto/git.md#git-log-secret
 
+#### Desktop app
+
+Follow [this
+documentation](https://github.com/zulip/zulip-desktop/blob/main/development.md)
+to set up the Zulip Desktop development environment.
+
+#### Terminal app
+
+Follow [this
+documentation](https://github.com/zulip/zulip-terminal?tab=readme-ov-file#setting-up-a-development-environment)
+to set up the Zulip Terminal development environment.
+
+## Finding an issue to work on
+
 ### Where to look for an issue
 
 Now you're ready to pick your first issue! Zulip has several repositories you
@@ -245,16 +218,21 @@ a chat thread in addition to the GitHub issue.
 Please follow the same guidelines as described above: find an issue labeled
 "help wanted", and only pick up one issue at a time to start with.
 
-### Getting help
+## Getting help
 
 You may have questions as you work on your pull request. For example, you might
 not be sure about some details of what's required, or have questions about your
-implementation approach.
+implementation approach. Zulip's maintainers are happy to answer thoughtfully
+posed questions, and discuss any difficulties that might arise as you work on
+your PR.
 
-Zulip's maintainers are happy to answer thoughtfully posed questions, and
+If you haven't done so yet, now is the time to join the [Zulip development
-discuss any difficulties that might arise as you work on your PR. You can get
+community](https://zulip.com/development-community/). If you'd like, introduce
-help in public channels in the [Zulip development
+yourself in the [#new
-community](https://zulip.com/development-community/):
+members](https://chat.zulip.org/#narrow/channel/95-new-members) channel, using
+your name as the [topic](https://zulip.com/help/introduction-to-topics).
+
+You can get help in public channels in the community:
 
 1. **Review** the [Zulip development community
    guidelines](https://zulip.com/development-community/#community-norms).
@@ -281,7 +259,39 @@ Well-posed questions will generally get a response within 1-2 business days.
 There is no need to @-mention anyone when you ask a question, as maintainers
 keep a close eye on all the ongoing discussions.
 
-### Submitting a pull request
+## What makes a great Zulip contributor?
+
+As you're working on your first code contribution, here are some best practices
+to keep in mind.
+
+- [Asking great questions][great-questions]. It's very hard to answer a general
+  question like, "How do I do this issue?" When asking for help, explain your
+  current understanding, including what you've done or tried so far and where
+  you got stuck. Post tracebacks or other error messages if appropriate. For
+  more advice, check out [our guide][great-questions]!
+- Learning and practicing
+  [Git commit discipline](https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html).
+- Submitting carefully tested code. See our [detailed guide on how to review
+  code](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#how-to-review-code)
+  (yours or someone else's).
+- Posting
+  [screenshots or GIFs](https://zulip.readthedocs.io/en/latest/tutorials/screenshot-and-gif-software.html)
+  for frontend changes.
+- Working to [make your pull requests easy to
+  review](https://zulip.readthedocs.io/en/latest/contributing/reviewable-prs.html).
+- Clearly describing what you have implemented and why. For example, if your
+  implementation differs from the issue description in some way or is a partial
+  step towards the requirements described in the issue, be sure to call
+  out those differences.
+- Being responsive to feedback on pull requests. This means incorporating or
+  responding to all suggested changes, and leaving a note if you won't be
+  able to address things within a few days.
+- Being helpful and friendly on the [Zulip community
+  server](https://zulip.com/development-community/).
+
+[great-questions]: https://zulip.readthedocs.io/en/latest/contributing/asking-great-questions.html
+
+## Submitting a pull request
 
 See the [guide on submitting a pull
 request](https://zulip.readthedocs.io/en/latest/contributing/reviewable-prs.html)
@@ -295,7 +305,7 @@ how to help the review process move forward.
 It's OK if your first issue takes you a while; that's normal! You'll be able to
 work a lot faster as you build experience.
 
-### Beyond the first issue
+## Beyond the first issue
 
 To find a second issue to work on, we recommend looking through issues with the same
 `area:` label as the last issue you resolved. You'll be able to reuse the
@@ -303,10 +313,7 @@ work you did learning how that part of the codebase works. Also, the path to
 becoming a core developer often involves taking ownership of one of these area
 labels.
 
-For more advice, see [What makes a great Zulip
+## Common questions
-contributor?](#what-makes-a-great-zulip-contributor) below.
-
-### Common questions
 
 - **What if somebody is already working on the issue I want to claim?** There
   are lots of issue to work on! If somebody else is actively working on the
@@ -382,63 +389,6 @@ contributor?](#what-makes-a-great-zulip-contributor) below.
 
 [reviewable-pull-requests]: https://zulip.readthedocs.io/en/latest/contributing/reviewable-prs.html
 
-## What makes a great Zulip contributor?
-
-Zulip has a lot of experience working with new contributors. In our
-experience, these are the best predictors of success:
-
-- [Asking great questions][great-questions]. It's very hard to answer a general
-  question like, "How do I do this issue?" When asking for help, explain your
-  current understanding, including what you've done or tried so far and where
-  you got stuck. Post tracebacks or other error messages if appropriate. For
-  more advice, check out [our guide][great-questions]!
-- Learning and practicing
-  [Git commit discipline](https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html).
-- Submitting carefully tested code. See our [detailed guide on how to review
-  code](https://zulip.readthedocs.io/en/latest/contributing/code-reviewing.html#how-to-review-code)
-  (yours or someone else's).
-- Posting
-  [screenshots or GIFs](https://zulip.readthedocs.io/en/latest/tutorials/screenshot-and-gif-software.html)
-  for frontend changes.
-- Working to [make your pull requests easy to
-  review](https://zulip.readthedocs.io/en/latest/contributing/reviewable-prs.html).
-- Clearly describing what you have implemented and why. For example, if your
-  implementation differs from the issue description in some way or is a partial
-  step towards the requirements described in the issue, be sure to call
-  out those differences.
-- Being responsive to feedback on pull requests. This means incorporating or
-  responding to all suggested changes, and leaving a note if you won't be
-  able to address things within a few days.
-- Being helpful and friendly on the [Zulip community
-  server](https://zulip.com/development-community/).
-
-[great-questions]: https://zulip.readthedocs.io/en/latest/contributing/asking-great-questions.html
-
-## User feedback
-
-Nearly every feature we develop starts with a user request. If you are part
-of a group that is either using or considering using Zulip, we would love to
-hear about your experience with the product. If you're not sure what to
-write, here are some questions we're always very curious to know the answer
-to:
-
-- Evaluation: What is the process by which your organization chose or will
-  choose a group chat product?
-- Pros and cons: What are the pros and cons of Zulip for your organization,
-  and the pros and cons of other products you are evaluating?
-- Features: What are the features that are most important for your
-  organization? In the best-case scenario, what would your chat solution do
-  for you?
-- Onboarding: If you remember it, what was your impression during your first
-  few minutes of using Zulip? What did you notice, and how did you feel? Was
-  there anything that stood out to you as confusing, or broken, or great?
-- Organization: What does your organization do? How big is the organization?
-  A link to your organization's website?
-
-You can contact us in the [#feedback channel of the Zulip development
-community](https://chat.zulip.org/#narrow/channel/137-feedback) or
-by emailing [support@zulip.com](mailto:support@zulip.com).
-
 ## Outreach programs
 
 Zulip regularly participates in [Google Summer of Code
@@ -455,34 +405,3 @@ more about participating in an outreach program with Zulip. Most of our program
 participants end up sticking around the project long-term, and many have become
 core team members, maintaining important parts of the project. We hope you
 apply!
-
-## Stay connected
-
-Even if you are not logging into the development community on a regular basis,
-you can still stay connected with the project.
-
-- Follow us [on Twitter](https://twitter.com/zulip).
-- Subscribe to [our blog](https://blog.zulip.org/).
-- Join or follow the project [on LinkedIn](https://www.linkedin.com/company/zulip-project/).
-
-## Help others find Zulip
-
-Here are some ways you can help others find Zulip:
-
-- Star us on GitHub. There are four main repositories:
-  [server/web](https://github.com/zulip/zulip),
-  [Flutter mobile](https://github.com/zulip/zulip-flutter),
-  [desktop](https://github.com/zulip/zulip-desktop), and
-  [Python API](https://github.com/zulip/python-zulip-api).
-
-- "Like" and retweet [our tweets](https://twitter.com/zulip).
-
-- Upvote and post feedback on Zulip on comparison websites. A couple specific
-  ones to highlight:
-
-  - [AlternativeTo](https://alternativeto.net/software/zulip-chat-server/). You can also
-    [upvote Zulip](https://alternativeto.net/software/slack/) on their page
-    for Slack.
-  - [Add Zulip to your stack](https://stackshare.io/zulip) on StackShare, star
-    it, and upvote the reasons why people like Zulip that you find most
-    compelling.

README.md

@@ -43,7 +43,7 @@ Come find us on the [development community chat](https://zulip.com/development-c
   issue](https://zulip.readthedocs.io/en/latest/contributing/contributing.html#reporting-issues),
   [translate](https://zulip.readthedocs.io/en/latest/translating/translating.html)
   Zulip into your language, or [give us
-  feedback](https://zulip.readthedocs.io/en/latest/contributing/contributing.html#user-feedback).
+  feedback](https://zulip.readthedocs.io/en/latest/contributing/suggesting-features.html).
   We'd love to hear from you, whether you've been using Zulip for years, or are just
   trying it out for the first time.
 

docs/contributing/how-we-communicate.md

@@ -3,10 +3,10 @@
 The primary communication forum for the Zulip community is the Zulip server
 hosted at [chat.zulip.org](https://chat.zulip.org/). If you are not familiar
 with it, start by reading the [Zulip development community
-section](contributing.md#zulip-development-community) of the contributing guide.
+guide](https://zulip.com/development-community/). The guidelines here also apply
-The guidelines here also apply to how we communicate on GitHub issues and pull
+to how we communicate on GitHub issues and pull requests, but other pages in
-requests, but other pages in this section go into greater detail about
+this section go into greater detail about expectations that are specific to pull
-expectations that are specific to pull requests.
+requests.
 
 We are deeply committed to maintaining a respectful, collaborative atmosphere in
 across all interactions in the Zulip community. To get a feel for what that

docs/contributing/suggesting-features.md

@@ -85,3 +85,27 @@ for a feature or improvement. Steps and best practices for filing an issue:
    message](https://zulip.com/help/link-to-a-message-or-conversation#get-a-link-to-a-specific-message)
    in the discussion thread, as message links will still work even if the topic is
    renamed or resolved.
+
+## Evaluation and onboarding feedback
+
+If you have been involved in the decision to use (or not use!) Zulip, or are
+currently considering it, we'd love to hear about it. You can contact us
+publicly in the [#feedback](https://chat.zulip.org/#narrow/channel/137-feedback)
+channel in the [Zulip development
+community](https://zulip.com/development-community/), or privately at
+[feedback@zulip.com](mailto:feedback@zulip.com).
+
+Here are some questions we're especially interested in:
+
+- **Who you are**: Tell us a bit about your organization. What does it do? How many
+  people are involved?
+- **Evaluation**: What is the process by which your organization chose or will
+  choose a team chat product?
+- **Pros and cons**: What are the pros and cons of Zulip for your organization,
+  and the pros and cons of other products you are evaluating?
+- **Features**: What are the features that are most important for your
+  organization? In the best-case scenario, what would your chat solution do
+  for you?
+- **Onboarding**: If you remember, what were your impressions during your first
+  few minutes of using Zulip? What did you notice, and how did you feel? Was
+  there anything that stood out to you as confusing, or unexpected, or great?

docs/overview/release-lifecycle.md

@@ -193,8 +193,8 @@ love to hear from you, either in
 GitHub issue. Please an include an explanation of your use case: such details
 can be extremely helpful in designing appropriately general solutions, and also
 helps us identify cases where an existing solution can solve your problem. See
-our guides for [reporting bugs](../contributing/reporting-bugs.md) and [giving
+our guide on [suggesting features and
-feedback](../contributing/contributing.md#user-feedback) for more details.
+improvements](../contributing/suggesting-features.md) for more details.
 
 ## Client apps