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
handful of longer guides.

The feature articles serve a few different purposes:

Feature discovery, for someone browsing the /help page, and looking at
the set of titles.

Public documentation of our featureset, 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
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.

The user documentation is available under /help/ on any Zulip server;
(e.g. https://chat.zulip.org/help/ or http://localhost:9991/help/ in
the Zulip development environment). The user documentation is not hosted 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
templates/zerver/help/ in the
main Zulip server repository. The file
foo.md is automatically rendered by the render_markdown_path function in
zerver/templatetags/app_filters.py when the user accesses a URL of the
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
adding to or editing the collection of markdown files under
templates/zerver/help. If you have the Zulip development environment
setup, you simply need to reload your browser on
http://localhost:9991/help/foo to see the latest version of foo.md
rendered.

When you refer to the features in the Zulip UI, you should bold the
feature’s name followed by the feature itself (e.g. Settings page,
Change password button, Email field). No quotation marks should be
used.

Keep in mind that the UI may change — don’t describe it in more detail than
is needed. Never identify or refer to a button by its color.

Images and screenshots should be included in user documentation only
if it will help guide the user in how to do something (e.g. if 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
result of an interaction with the UI.

Using too many screenshots creates maintainability problems (we have
to update them every time the UI is changed) and also can make the
instructions for something simple look long and complicated.

When taking screenshots, the image should never include the whole
Zulip browser window in a screenshot; instead, it should only show
relevant parts of the app. In addition, the screenshot should always
come after the text that describes it, never before.

Images are often a part of a numbered step and must be indented four spaces
to be formatted correctly.

You can refer to features in the Zulip UI by referencing their names
and their FontAwesome (version 4.7.0) text
icons within parentheses. Note: We have completed migrating away from older
base class icon-vector and have dropped support for it. We now only support
icons from FontAwesome (version 4.7.0) which
make use of fa as a base class.

A tip is any suggestion for the user that is not part of the main set of
instructions. For instance, it may address a common problem users may
encounter while following the instructions, or point to an option for power
users.

!!! tip ""
If you've forgotten your password, see the
[Change your password](/help/change-your-password) page for
instructions on how to reset it.

A warning is a note on what happens when there is some kind of problem.
Tips are more common than warnings.

!!! warn ""
**Note:** If you attempt to input a nonexistent stream name, an error
message will appear.

All tips/warnings should appear inside tip/warning blocks. There should be
only one tip/warning inside each block.They usually be formatted as a
continuation of a numbered step.