mirror of https://github.com/zulip/zulip.git
448 lines
18 KiB
Markdown
448 lines
18 KiB
Markdown
# 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 help center 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 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 explanations for new Zulip users and admins, especially for
|
||
organization settings.
|
||
|
||
Zulip help center 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 help center 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 help center documentation is the Markdown files under
|
||
`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 `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 help center documentation
|
||
by just adding to or editing the collection of Markdown files under
|
||
`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.
|
||
|
||
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 help center articles
|
||
|
||
Writing documentation is a different form of writing than most people have
|
||
experience with.
|
||
|
||
### Getting started
|
||
|
||
There are over 100 feature articles and longer guides in the
|
||
[Zulip help center](https://zulip.com/help/), so make the most of
|
||
the current documentation 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. Preferences, 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](#writing-style) used, as well as any
|
||
[Markdown features](#markdown-features) used to enhance 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 `help/` and start working
|
||
on updating it with content about the new feature.
|
||
|
||
- If not, choose an existing article to use as a template for your
|
||
new article and make a list of which articles (or guides) would be
|
||
good to link to 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/channel/19-documentation)
|
||
on the [Zulip community server](https://zulip.com/development-community/).
|
||
|
||
### Updating an existing article
|
||
|
||
If the new feature you're documenting is a refinement on,
|
||
or related to, a feature that already has a dedicated help center
|
||
article, the information will be more useful and discoverable for
|
||
users as an addition to the existing article.
|
||
|
||
Here are some things to keep in mind when expanding and updating
|
||
existing help center articles:
|
||
|
||
- Maintain the format and [writing style](#writing-style) of the
|
||
current article.
|
||
|
||
- Review the [Markdown features](#markdown-features) available and
|
||
pay attention to the ones already utilized in the article.
|
||
|
||
- Think about where inline links to other help center documentation
|
||
would be appropriate in the description of the feature. For example,
|
||
your new feature might relate to general Zulip features like
|
||
[keyboard shortcuts](https://zulip.com/help/keyboard-shortcuts)
|
||
or [channels and topics](https://zulip.com/help/streams-and-topics).
|
||
|
||
- Make sure there is a **Related articles** section at the end
|
||
of the article that again links to any help center documentation
|
||
mentioned in the text or related to the feature.
|
||
|
||
If your updates to the existing article will change the name of the
|
||
markdown file, then see section below on [redirecting an existing
|
||
article](#redirecting-an-existing-article).
|
||
|
||
Creating robust and informative help center articles with good links
|
||
will allow users to navigate the help center much more effectively.
|
||
|
||
### Adding a new article
|
||
|
||
If the feature you're documenting needs a new article, here are some
|
||
things to keep in mind, in addition to the points made above for
|
||
updating existing documentation:
|
||
|
||
- 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.
|
||
|
||
- Fewer words is better than more. Many Zulip users have English as a second
|
||
language.
|
||
|
||
- 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.
|
||
|
||
An anti-pattern is trying to make up for bad UX by adding help center
|
||
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), interacting
|
||
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.
|
||
|
||
### Redirecting an existing article
|
||
|
||
From time to time, we might want to rename an article in the help
|
||
center, or REST API documentation. This change will break incoming
|
||
links, including links in published Zulip blog posts, links in other
|
||
branches of the repository that haven't been rebased, and more
|
||
importantly links from previous versions of Zulip.
|
||
|
||
To fix these broken links, you can easily add a URL redirect in:
|
||
`zerver/lib/url_redirects.py`.
|
||
|
||
For help center documentation, once you've renamed the file in your
|
||
branch (e.g., `git mv path/to/foo.md path/to/bar.md`), go to
|
||
`url_redirects.py` and add a new `URLRedirect` to the
|
||
`HELP_DOCUMENTATION_REDIRECTS` list:
|
||
|
||
```python
|
||
HELP_DOCUMENTATION_REDIRECTS: List[URLRedirect] = [
|
||
# Add URL redirects for help center documentation here:
|
||
URLRedirect("/help/foo", "/help/bar"),
|
||
...
|
||
```
|
||
|
||
Note that you will also need to add redirects when you're deleting
|
||
a help center article and adding its content to an existing article
|
||
as a section. In that case, the new URL will include the new section
|
||
header: `URLRedirect("/help/foo", "/help/bar#new-section-header"),`.
|
||
|
||
For REST API documentation, you will either need to rename the file
|
||
as above, or you will need to update the endpoint's `operationId` in
|
||
`zerver/openapi/zulip.yaml`. Then, you would add a new `URLRedirect`
|
||
to the `API_DOCUMENTATION_REDIRECTS` list in `url_redirects.py`.
|
||
|
||
You should still check for references to the old URL in your branch
|
||
and replace those with the new URL (e.g., `git grep "/help/foo"`).
|
||
Updating section headers in existing help center articles does not
|
||
require adding a URL redirect, but you will need to update any
|
||
existing links to that article's section in your branch.
|
||
|
||
If you have the Zulip development environment set up, you can manually
|
||
test your changes by loading the old URL in your browser (e.g.,
|
||
`http://localhost:9991/help/foo`), and confirming that it redirects to
|
||
the new url (e.g., `http://localhost:9991/help/bar`).
|
||
|
||
There is also an automated test in `zerver/tests/test_urls.py` that
|
||
checks all the URL redirects, which you can run from the command line:
|
||
|
||
```console
|
||
./tools/test-backend zerver.tests.test_urls.URLRedirectTest
|
||
```
|
||
|
||
## Writing style
|
||
|
||
Below are some general style and writing conventions that should be used
|
||
as guidance when documenting Zulip's features.
|
||
|
||
### User interface
|
||
|
||
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. Use **bold** for channel names, and quotation marks for topic names.
|
||
|
||
Keep in mind that the UI may change — don’t describe it in more detail than
|
||
is needed. In particular:
|
||
|
||
- Do not specify what the default configuration is. This might change in the
|
||
future, or may even be different for different types of organizations.
|
||
- Do not list out the options the user is choosing from. Once the user finds the
|
||
right menu in the UI, they'll be able to see the options. In some cases, we
|
||
may describe the options in more detail outside of the instructions block.
|
||
- Never identify or refer to a button by its color. You _can_ describe its
|
||
location.
|
||
- Use screenshots only when it's very difficult to get your point across without
|
||
them.
|
||
|
||
### Voice
|
||
|
||
Do not use `we` to refer to Zulip or its creators; for example, "Zulip also
|
||
allows ...", rather than "we also allow ...". On the other hand, `you` is ok
|
||
and used liberally.
|
||
|
||
### Keyboard shortcuts
|
||
|
||
Surround each keyboard key in the shortcut with `<kbd>` HTML element start and
|
||
end tags (e.g., `<kbd>Enter</kbd>` or `<kbd>R</kbd>`).
|
||
|
||
For shortcuts with more than one key, add a plus sign (+) surrounded by spaces
|
||
in between the keys (e.g., `<kbd>Ctrl</kbd> + <kbd>K</kbd>`). Any shortcut for
|
||
an arrow key (↑, ↓, ←, →) will also need the `"arrow-key"` CSS class included
|
||
in the `<kbd>` start tag (e.g., ` <kbd class="arrow-key">↑</kbd>`).
|
||
|
||
Use the labels one sees on the actual keyboard rather than the letter they
|
||
produce when pressed (e.g. `R` and `Shift` + `R` rather than `r` and `R`).
|
||
For symbols, such as `?` or `@`, that are produced through key combinations that
|
||
change depending on the user's keyboard layout, you should use the symbol as it
|
||
appears on a keyboard instead of any specific combination of keys.
|
||
|
||
Use non-Mac keyboard keys; for example `Enter`, instead of `Return`. Zulip will
|
||
automatically translate non-Mac keys to the Mac versions for users with a Mac
|
||
user agent. If you want to confirm that your documentation is rendering Mac keys
|
||
correctly when writing documentation in Windows or Linux, you can temporarily
|
||
change `has_mac_keyboard` in `/web/src/common.ts` to always return `True`.
|
||
Then when you view your documentation changes in the development environment,
|
||
the keyboard shortcuts should be rendered with Mac keys where appropriate.
|
||
|
||
If you're adding a tip to an article about a keyboard shortcut, you
|
||
should use the more specific keyboard [tip macro](#tips-and-warnings),
|
||
`!!! keyboard_tip ""`. In general, all keyboard shortcuts should be
|
||
documented on the [keyboard
|
||
shortcuts](https://zulip.com/help/keyboard-shortcuts) help center
|
||
article.
|
||
|
||
## 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](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, if needed.
|
||
|
||
- Inline [icons](#icons) are used to refer to features in the Zulip UI.
|
||
|
||
- Utilize [macros](#macros) to limit repeated content in the documentation.
|
||
|
||
- Create special highlight warning blocks using
|
||
[tips and warnings](#tips-and-warnings).
|
||
|
||
- Format instructions with tabs using
|
||
[Markdown tab switcher](#tab-switcher).
|
||
|
||
### Images
|
||
|
||
Images and screenshots should be included in help center documentation
|
||
only if they 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.
|
||
|
||
### Icons
|
||
|
||
You can refer to features in the Zulip UI by referencing their names
|
||
and their [FontAwesome](https://fontawesome.com/v4.7.0/) (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](https://fontawesome.com/v4.7.0/) (version 4.7.0) which
|
||
make use of `fa` as a base class.
|
||
|
||
- **cog** (<i class="fa fa-cog"></i>) icon:
|
||
`**cog** (<i class="fa fa-cog"></i>) icon`
|
||
- **down chevron** (<i class="fa fa-chevron-down"></i>) icon:
|
||
`**down chevron** (<i class="fa fa-chevron-down"></i>) icon`
|
||
- **eye** (<i class="fa fa-eye"></i>) icon:
|
||
`**eye** (<i class="fa fa-eye"></i>) icon`
|
||
- **file** (<i class="fa fa-file-code-o"></i>) icon:
|
||
`**file** (<i class="fa fa-file-code-o"></i>) icon`
|
||
- **filled star** (<i class="fa fa-star"></i>) icon:
|
||
`**filled star** (<i class="fa fa-star"></i>) icon`
|
||
- **formatting** (<i class="fa fa-font"></i>) icon:
|
||
`**formatting** (<i class="fa fa-font"></i>) icon`
|
||
- **menu** (<i class="fa fa-bars"></i>) icon:
|
||
`**menu** (<i class="fa fa-bars"></i>) icon`
|
||
- **verflow** ( <i class="fa fa-ellipsis-v"></i> ) icon:
|
||
`**overflow** ( <i class="fa fa-ellipsis-v"></i> ) icon`
|
||
- **paperclip** (<i class="fa fa-paperclip"></i>) icon:
|
||
`**paperclip** (<i class="fa fa-paperclip"></i>) icon`
|
||
- **pencil** (<i class="fa fa-pencil"></i>) icon:
|
||
`**pencil** (<i class="fa fa-pencil"></i>) icon`
|
||
- **pencil and paper** (<i class="fa fa-pencil-square-o"></i>) icon:
|
||
`**pencil and paper** (<i class="fa fa-pencil-square-o"></i>) icon`
|
||
- **plus** (<i class="fa fa-plus"></i>) icon:
|
||
`**plus** (<i class="fa fa-plus"></i>) icon`
|
||
- **smiley face** (<i class="fa fa-smile-o"></i>) icon:
|
||
`**smiley face** (<i class="fa fa-smile-o"></i>) icon`
|
||
- **star** (<i class="fa fa-star-o"></i>) icon:
|
||
`**star** (<i class="fa fa-star-o"></i>) icon`
|
||
- **trash** (<i class="fa fa-trash-o"></i>) icon:
|
||
`**trash** (<i class="fa fa-trash-o"></i>) icon`
|
||
- **video-camera** (<i class="fa fa-video-camera"></i>) icon:
|
||
`**video-camera** (<i class="fa fa-video-camera"></i>) icon`
|
||
- **x** (<i class="fa fa-times"></i>) icon:
|
||
`**x** (<i class="fa fa-times"></i>) icon`
|
||
|
||
### Macros
|
||
|
||
**Macros** are elements in the format of `{!macro.md!}` that insert common
|
||
phrases and steps at the location of the macros. Macros help eliminate
|
||
repeated content in our documentation.
|
||
|
||
The source for macros is the Markdown files under `help/include` in the
|
||
[main Zulip server repository](https://github.com/zulip/zulip).
|
||
|
||
- **Administrator only feature** `{!admin-only.md!}`: Notes that the feature
|
||
is only available to organization administrators.
|
||
|
||
- **Message actions** `{!message-actions.md!}`: First step to navigating to
|
||
the on-hover message actions.
|
||
|
||
- **Message actions menu** `{!message-actions-menu.md!}`: Navigate to the
|
||
message actions menu.
|
||
|
||
- **Save changes** `{!save-changes.md!}`: Save changes after modifying
|
||
organization settings.
|
||
|
||
- **Channel actions** `{!channel-actions.md!}`: Navigate to the channel actions
|
||
menu from the left sidebar.
|
||
|
||
- **Start composing** `{!start-composing.md!}`: Open the compose box.
|
||
|
||
### Tips and warnings
|
||
|
||
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.
|
||
|
||
```md
|
||
!!! 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 **keyboard tip** is a note for users to let them know that the same action
|
||
can also be accomplished via a [keyboard shortcut](#keyboard-shortcuts).
|
||
|
||
```md
|
||
!!! keyboard_tip ""
|
||
|
||
Use <kbd>D</kbd> to bring up your list of drafts.
|
||
```
|
||
|
||
A **warning** is a note on what happens when there is some kind of problem.
|
||
Tips are more common than warnings.
|
||
|
||
```md
|
||
!!! warn ""
|
||
|
||
**Note:** If you attempt to input a nonexistent channel 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, and they usually
|
||
should be formatted as a continuation of a numbered step.
|
||
|
||
### Tab switcher
|
||
|
||
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 help center articles,
|
||
languages in API docs, etc. To create a tab switcher, write:
|
||
|
||
```md
|
||
{start_tabs}
|
||
{tab|desktop-web}
|
||
# First tab's content
|
||
{tab|ios}
|
||
# Second tab's content
|
||
{tab|android}
|
||
# Third tab's content
|
||
{end_tabs}
|
||
```
|
||
|
||
The tab identifiers (e.g. `desktop-web` above) and their mappings to
|
||
the tabs' labels are declared in
|
||
[zerver/lib/markdown/tabbed_sections.py][tabbed-sections-code].
|
||
|
||
[tabbed-sections-code]: https://github.com/zulip/zulip/blob/main/zerver/lib/markdown/tabbed_sections.py
|
||
|
||
This widget can also be used just to create a nice box around a set of
|
||
instructions
|
||
([example](https://zulip.com/help/deactivate-your-account)) by
|
||
only declaring a single tab.
|