documentation: Update tutorial for writing help center documentation.

Updates the tutorial for writing help center articles to encourage
contributors to add to or enhance the existing help center docs
before writing a new articles for new features.

Also, generally updates references to 'user documentation' to be
'help center documentation'.

Additionally, updates some headers within the tutorials for clarity
and consistency, and adds some linkifying throughout the section on
writing documentation.

docs/documentation/overview.md

@@ -2,27 +2,27 @@
 
 Zulip has three major documentation systems:
 
-- Developer and sysadmin documentation: Documentation for people
+- **Developer and sysadmin documentation**: Documentation for people
   actually interacting with the Zulip codebase (either by developing
   it or installing it), and written in Markdown.
 
-- Core website documentation: Complete webpages for complex topics,
+- **Core website documentation**: Complete webpages for complex topics,
   written in HTML, JavaScript, and CSS (using the Django templating
   system). These roughly correspond to the documentation someone
   might look at when deciding whether to use Zulip. We don't expect
   to ever have more than about 10 pages written using this system.
 
-- User-facing documentation: Our scalable system for documenting
+- **User-facing documentation**: Our scalable system for documenting
   Zulip's huge collection of specific features without a lot of
   overhead or duplicated code/syntax, written in Markdown. We have
   several hundred pages written using this system. There are 3
   branches of this documentation:
-  - User documentation (with a target audience of individual Zulip
+  - [Help center documentation](#help-center-documentation)
-    users),
+    (with a target audience of individual Zulip users)
-  - Integrations documentation (with a target audience of IT folks
+  - [Integrations documentation](#integrations-documentation)
-    setting up integrations), and
+    (with a target audience of IT folks setting up integrations)
-  - API documentation (with a target audience of developers writing
+  - [API documentation](#api-documentation) (with a target audience
-    code to extend Zulip).
+    of developers writing code to extend Zulip)
 
 These three systems are documented in detail.
 
@@ -89,20 +89,21 @@ unless there's a good reason, but we don't intend to migrate them,
 either, since this system gives us the flexibility to express these
 important elements of the product clearly.
 
-## User facing documentation
+## User-facing documentation
 
 All of these systems use a common Markdown-based framework with
 various extensions for macros and variable interpolation,
 (`render_markdown_path` in the code), designed to make it convenient
 to do the things one does a lot in each type of documentation.
 
-### End user documentation
+### Help center documentation
 
 Zulip's [help center](https://zulip.com/help/) documentation is
 designed to explain how the product works to end users. We aim for
 this to be clear, concise, correct, and readable to nontechnical
-audiences where possible. See our guide on [writing user
+audiences where possible.
-documentation](user.md).
+
+See our guide on [writing help center articles](user.md).
 
 ### Integrations documentation
 

docs/documentation/user.md

@@ -1,36 +1,31 @@
-# User documentation
+# Writing help center articles
 
 Our goal is for Zulip to have complete, high-quality
 documentation about Zulip's features and how to perform certain tasks, such
 as setting up an organization.
 
-There are two types of documents: articles about specific features, and a
+There are two types of help center documents: articles about specific features,
-handful of longer guides.
+and a handful of longer guides. The feature articles serve a few different purposes:
 
-The feature articles serve a few different purposes:
+- Feature discovery, for someone browsing the `/help/` page, and looking at
+  the set of articles and guides.
+
+- Public documentation of our feature set, for someone googling "can zulip do ..."
+
+- Quick responses to support questions; if someone emails a Zulip admin
+  asking "How do I change my name?", they can reply with a link to the doc.
 
-- Feature discovery, for someone browsing the `/help` page, and looking at
-  the set of titles.
-- Public documentation of our feature set, for someone googling "can zulip do .."
-- Canned responses to support questions; if someone emails a Zulip admin
-  asking "how do I change my name", they can reply with a link to the doc.
 - Feature explanations for new Zulip users and admins, especially for
   organization settings.
 
-This system is designed to make writing and maintaining such documentation
+Zulip help center documentation is available under `/help/` on any Zulip server;
-highly efficient. We link to the docs extensively from the landing pages and
-in-product, so it's important to keep the docs up to date.
-
-## Editing and testing
-
-The user documentation is available under `/help/` on any Zulip server;
 (e.g. <https://zulip.com/help/> or `http://localhost:9991/help/` in
-the Zulip development environment). The user documentation is not hosted on
+the Zulip development environment). The help center documentation is not hosted
-ReadTheDocs, since Zulip supports running a server completely disconnected
+on ReadTheDocs, since Zulip supports running a server completely disconnected
 from the Internet, and we'd like the documentation to be available in that
 environment.
 
-The source for this user documentation is the Markdown files under
+The source for help center documentation is the Markdown files under
 `templates/zerver/help/` in the
 [main Zulip server repository](https://github.com/zulip/zulip). The file
 `foo.md` is automatically rendered by the `render_markdown_path` function in
@@ -39,22 +34,63 @@ form `/help/foo`; with special cases for `/help/` going to `index.md` and
 `/help/unknown_article` going to `missing.md` (with a 404 response). Images
 are usually linked from `static/images/help/`.
 
-This means that you can contribute to the Zulip user documentation by just
+This means that you can contribute to the Zulip help center documentation
-adding to or editing the collection of Markdown files under
+by just adding to or editing the collection of Markdown files under
 `templates/zerver/help`. If you have the Zulip development environment
 set up, you simply need to reload your browser on
 `http://localhost:9991/help/foo` to see the latest version of `foo.md`
 rendered.
 
-## Writing documentation
+This system is designed to make writing and maintaining such documentation
+highly efficient. We link to the docs extensively from the landing pages and
+in-product, so it's important to keep the docs up to date.
+
+## Guide to writing documentation
 
 Writing documentation is a different form of writing than most people have
 experience with.
 
-Tips for adding a new article:
+### Getting started
 
-- Find an existing article in the same section of the help documentation,
+There are over 100 feature articles and longer guides in the
-  and copy the format, wording, style, etc as closely as you can.
+[Zulip help center](https://zulip.com/help/), so use that as a resource
+and guide as you begin.
+
+- Use the list on [Zulip help center home](https://zulip.com/help/)
+  to find the section of the docs (e.g. Display settings, Sending
+  messages, Reading messages, etc.) that relates to the new feature
+  you're documenting.
+
+- Read through the existing articles in that section and pay attention
+  to the writing style and [voice](#voice), as well as any
+  [Markdown features](#markdown-features) used to enchance the
+  readability of the documentation.
+
+- Should the feature you're documenting be added or merged into an
+  existing article? If so, you can locate that article in
+  `templates/zerver/help` and start working on updating it with
+  content about the new feature.
+
+- If not, make a list of which articles (or guides) would be good to
+  link to as **Related articles** in your new feature documentation.
+
+Remember that real estate in the left sidebar is somewhat precious.
+Minor features should rarely get their own article, and should instead
+be merged into the existing help center documentation where appropriate.
+
+If you are unsure about how and where to document the feature, you
+can always ask in
+[#documentation](https://chat.zulip.org/#narrow/stream/19-documentation)
+on the [Zulip community server](https://zulip.com/development-community/).
+
+### Adding a new article
+
+If the feature you're documenting needs a new article, here are some
+things to keep in mind:
+
+- Choose an existing article in the related section of the help
+  documentation, and copy the format, wording, style, etc. as closely
+  as you can.
 
 - If the feature exists in other team chat products, check out their
   documentation for inspiration.
@@ -65,17 +101,17 @@ Tips for adding a new article:
 - Try to put yourself in the shoes of a new Zulip user. What would you want
   to know?
 
+- Remember to explain the purpose of the feature and give context as well
+  as instructions for how to use or enable it.
+
 - The goal of user-facing documentation is not to be comprehensive. The goal
   is to give the right bits of information for the intended audience.
 
-- Real estate in the left sidebar is somewhat precious. Minor features
+An anti-pattern is trying to make up for bad UX by adding help center
-  should rarely get their own article.
-
-An anti-pattern is trying to make up for bad UX by adding user
 documentation. It's worth remembering that for most articles, almost 100% of
 the users of the feature will never read the article. Instructions for
-filling out forms, interacting with UI widgets (e.g. typeaheads),
+filling out forms, interacting with UI widgets (e.g. typeaheads), interacting
-interacting with modals, etc. should never go in user documentation.
+with modals, etc. should never go in the help center documentation.
 In such cases, you may be able to fix the problem by adding text in-app,
 where the user will see it as they are interacting with the feature.
 
@@ -91,31 +127,40 @@ is needed. **Never identify or refer to a button by its color.**
 
 ### Voice
 
-Do not use `we` to refer to Zulip or its creators; e.g. "Zulip also
+Do not use `we` to refer to Zulip or its creators; for example, "Zulip also
-allows .." rather than "we also allow ..". `You` is ok and used liberally.
+allows ...", rather than "we also allow ...". On the other hand, `you` is ok
+and used liberally.
 
-## Features
+## Markdown features
 
 Zulip's Markdown processor allows you to include several special features in
 your documentation to help improve its readability:
 
 - Since raw HTML is supported in Markdown, you can include arbitrary
   HTML/CSS in your documentation as needed.
-- Code blocks allow you to highlight syntax, similar to Zulip's own Markdown.
+
+- Code blocks allow you to highlight syntax, similar to
+  [Zulip's own Markdown](https://zulip.com/help/format-your-message-using-markdown).
+
 - Anchor tags can be used to link to headers in other documents.
-- [Images](#images) of Zulip UI can be added to documentation.
+
-- Inline [icons](#icons) used to refer to features in the Zulip UI.
+- [Images](#images) of Zulip UI can be added to documentation, if needed.
-- You can utilize [macros](#macros) to limit repeated content in the
+
-  documentation.
+- Inline [icons](#icons) are used to refer to features in the Zulip UI.
-- You can create special highlight warning blocks using
+
+- Utilize [macros](#macros) to limit repeated content in the documentation.
+
+- Create special highlight warning blocks using
   [tips and warnings](#tips-and-warnings).
-- You can create tabs using [Markdown tab switcher](#tab-switcher).
+
+- Format instructions with tabs using
+  [Markdown tab switcher](#tab-switcher).
 
 ### Images
 
-Images and screenshots should be included in user documentation only
+Images and screenshots should be included in help center documentation
-if they will help guide the user in how to do something (e.g. if the
+only if they will help guide the user in how to do something (e.g. if
-image will make it much clearer which element on the page the user
+the image will make it much clearer which element on the page the user
 should interact with). For instance, an image of an element should
 not be included if the element the user needs to interact with is the
 only thing on the page, but images can be included to show the end
@@ -237,7 +282,7 @@ should be formatted as a continuation of a numbered step.
 
 Our Markdown processor supports easily creating a tab switcher widget
 design to easily show the instructions for different
-[platforms](https://zulip.com/help/logging-out) in user docs,
+[platforms](https://zulip.com/help/logging-out) in help center articles,
 languages in API docs, etc. To create a tab switcher, write:
 
 ```md

docs/index.md

@@ -2,7 +2,7 @@
 
 Welcome! Zulip's documentation is split into four parts:
 
-- [User documentation](https://zulip.com/help), for users and
+- [Help center documentation](https://zulip.com/help), for users and
   administrators of Zulip organizations.
 - [Installation documentation](production/install.md), for
   installing and maintaining a production self-hosted Zulip installation.

docs/subsystems/realms.md

@@ -2,8 +2,8 @@
 
 Zulip allows multiple _realms_ to be hosted on a single instance.
 Realms are the Zulip codebases's internal name for what we refer to in
-user documentation as an organization (the name "realm" comes from
+user-facing documentation as an organization (the name "realm" comes
-[Kerberos](https://web.mit.edu/kerberos/)).
+from [Kerberos](https://web.mit.edu/kerberos/)).
 
 Wherever possible, we avoid using the term `realm` in any user-facing
 string or documentation; "Organization" is the equivalent term used in

docs/testing/testing.md

@@ -66,7 +66,7 @@ Additionally, Zulip also has about a dozen smaller tests suites:
 - `tools/test-documentation`: Checks for broken links in this
   ReadTheDocs documentation site.
 - `tools/test-help-documentation`: Checks for broken links in the
-  `/help` user documentation site, and related pages.
+  `/help/` help center documentation, and related pages.
 - `tools/test-api`: Tests that the API documentation at `/api`
   actually works; the actual code for this is defined in
   `zerver/openapi/python_examples.py`.

docs/translating/german.md

@@ -226,13 +226,13 @@ and there is no German equivalent, talking of "Views" is preferable in the
 developer documentation and makes it easier to rely on parts of the German
 _and_ parts of the English documentation.
 
-- View - **Ansicht** (User documentation)
+- View - **Ansicht** (User-facing documentation)
 
-For the user documentation, we want to use "Ansicht" instead of "view", as
+For user-facing documentation, we want to use "Ansicht" instead of "view",
-"Ansicht" provides a translated description for what you think of when hearing
+as "Ansicht" provides a translated description for what you think of when
-"view". "Ansicht" is not desirable for the developer documentation, since it
+hearing "view". "Ansicht" is not desirable for the developer documentation,
-does not emphasize the developing aspects of views (in contrast to anglicisms,
+since it does not emphasize the developing aspects of views (in contrast to
-which Germans often link to IT-related definitions).
+anglicisms, which Germans often link to IT-related definitions).
 
 _"Ansicht" (Transifex)_
 

docs/tutorials/new-feature-tutorial.md

@@ -156,10 +156,11 @@ any existing documentation that might be relevant to the new feature.
 For detailed information on the kinds of documentation Zulip has, see
 [Documentation](../documentation/overview.md).
 
-**End user documentation:** You will likely need to at least update,
+**Help center documentation:** You will likely need to at least update,
-extend and link to `/help` articles that are related to your new
+extend and link to `/help/` articles that are related to your new
-feature. See [User documentation](../documentation/user.md) for more
+feature. [Writing help center articles](../documentation/user.md)
-detailed information about writing and editing feature `/help` articles.
+provides more detailed information about writing and editing feature
+`/help/` articles.
 
 **API documentation:** A new feature will probably impact the REST API
 documentation as well, which will mean updating `zerver/openapi/zulip.yaml`
@@ -686,15 +687,15 @@ important to make sure that your new feature is well documented.
 This example feature adds new functionality that requires messages to
 have topics if the setting is enabled. A recommended way to document
 this feature would be to update and/or augment Zulip's existing
-[end user documentation (Help Center)](https://zulip.com/help/)
+[help center documentation](https://zulip.com/help/) to reflect your
-to reflect your changes and additions.
+changes and additions.
 
 At the very least, this will involve modifying (or adding) a Markdown
 file documenting the feature to `templates/zerver/help/` in the main
 Zulip server repository, where the source for Zulip's end user
 documentation is stored. Details about writing, editing and testing
 these Markdown files can be found in:
-[User documentation](../documentation/user.md).
+[Writing help center articles](../documentation/user.md).
 
 Also, new features will often impact Zulip's REST API documentation,
 which is found in `zerver/openapi/zulip.yaml`. You may have noticed