From 0b596159c1eaf4aa16ba0c0aea51380b6576b059 Mon Sep 17 00:00:00 2001 From: Karl Stolley Date: Fri, 16 Jun 2023 13:36:09 -0500 Subject: [PATCH] docs: Adjust wording and phrasing for clarity. --- docs/contributing/reporting-bugs.md | 25 ++++++++++++------------ docs/contributing/suggesting-features.md | 8 ++++---- 2 files changed, 17 insertions(+), 16 deletions(-) diff --git a/docs/contributing/reporting-bugs.md b/docs/contributing/reporting-bugs.md index 7f799275ac..10294b852f 100644 --- a/docs/contributing/reporting-bugs.md +++ b/docs/contributing/reporting-bugs.md @@ -91,8 +91,8 @@ Steps and best practices for starting a conversation: have an account. 2. Pick an **appropriate stream** to report your issue: - [#issues](https://chat.zulip.org/#narrow/stream/9-issues) for issues with - the Zulip web app or server. A good default if you aren't sure which stream - to use. + the Zulip web app or server. Use this stream if you aren't sure which + stream is most appropriate. - [#mobile](https://chat.zulip.org/#narrow/stream/48-mobile) for issues with the mobile apps. - [#desktop](https://chat.zulip.org/#narrow/stream/16-desktop) for issues @@ -118,9 +118,9 @@ reproducible bug, a GitHub issue will be filed to keep track of it (see below). ## Managing bug reports -This section describes our bug management process. All community members are -encouraged to help make sure things run smoothly, whether or not they originally -reported the bug. +This section describes our process for managing bugs. All community members are +encouraged to help make sure this process runs smoothly, whether or not they +originally reported the bug. Whenever a bug is tracked in GitHub and also discussed in the development community, be sure to cross-link between the issue and the conversation. [Link @@ -139,16 +139,17 @@ renamed or resolved. an actual, reproducible bug, anyone can help out by filing a GitHub issue to track it: - In some cases, especially if we're planning to fix the issue right away, the - issue description can be a quote from a message with a link to the - discussion -- no need to stress over making it perfect. + GitHub issue description can simply quote and link to a message from the + discussion in the development community -- no need to stress over making it + perfect. - [Use Zulipbot](../contributing/zulipbot-usage.md) to add the appropriate - labels, including “bug” and at least one area label; leave a comment if you - don't know what area labels to use. + labels, including “bug” and at least one area label; leave a comment on + the issue if you don't know what area labels to use. - You can add the “help wanted” label (and claim the issue if you like) if that is appropriate based on the discussion. Note that sometimes we won't - mark a reproducible bug as “help wanted”, e.g., if we want a core - contributor to take it on, if the fix will happen as part of a larger - project, etc. + mark a reproducible bug as “help wanted” for various reasons. For example, + we might want a core contributor to take it on, or the fix might be planned + as part of a larger project. - Don't forget to cross-link between the issue and the discussion. - If a bug report in GitHub is not sufficiently clear, Zulip maintainers will often encourage the reporter to discuss it interactively in the development diff --git a/docs/contributing/suggesting-features.md b/docs/contributing/suggesting-features.md index edc78b3bc8..edf4721c28 100644 --- a/docs/contributing/suggesting-features.md +++ b/docs/contributing/suggesting-features.md @@ -35,8 +35,8 @@ Steps and best practices for starting a conversation: have an account. 2. Pick an **appropriate stream** to discuss your idea: - [#feedback](https://chat.zulip.org/#narrow/stream/137-feedback) for suggestions for - the Zulip web app or server. A good default if you aren't sure which stream - to use. + the Zulip web app or server. Use this stream if you aren't sure which stream is + most appropriate. - [#mobile](https://chat.zulip.org/#narrow/stream/48-mobile) for suggestions for the mobile apps. - [#desktop](https://chat.zulip.org/#narrow/stream/16-desktop) for suggestions @@ -77,8 +77,8 @@ for a feature or improvement. Steps and best practices for filing an issue: suggestions for the terminal app. 2. Do a **quick search** of the repository to see if there is already a similar request. If there is, add a comment explaining why you would also appreciate - the proposed change, and making any additional suggestions. Do not file a new - issue. + the proposed change, and make any additional suggestions you might have. Do + not file a new issue. 3. If you are aware of a related discussion in the Zulip development community, please **cross-link** between the issue and the discussion thread. [Link to a specific