Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/docs/documentation/helpcenter.md

448 lines
18 KiB
Markdown
Raw Normal View History

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.
2021-12-17 15:59:58 +01:00
# Writing help center articles
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
Our goal is for Zulip to have complete, high-quality
docs: Add notes on audience to user-docs.md.
2017-10-13 19:38:36 +02:00
documentation about Zulip's features and how to perform certain tasks, such
as setting up an organization.
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.
2021-12-17 15:59:58 +01:00
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:
docs: Add notes on audience to user-docs.md.
2017-10-13 19:38:36 +02:00
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.
2021-12-17 15:59:58 +01:00
- Feature discovery, for someone browsing the `/help/` page, and looking at
the set of articles and guides.
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
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.
2021-12-17 15:59:58 +01:00
- Public documentation of our feature set, for someone googling "can zulip do ..."
docs: Add notes on audience to user-docs.md.
2017-10-13 19:38:36 +02:00
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.
2021-12-17 15:59:58 +01:00
- 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.
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
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.
2021-12-17 15:59:58 +01:00
- Feature explanations for new Zulip users and admins, especially for
organization settings.
docs: Edit user documentation style guide a bit.
2017-01-17 07:12:29 +01:00
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.
2021-12-17 15:59:58 +01:00
Zulip help center documentation is available under `/help/` on any Zulip server;
docs: Remove incorrect references to chat.zulip.org. Most of these are Help Center links that should be pointing to the production Help Center.
2020-10-30 00:46:30 +01:00
(e.g. <https://zulip.com/help/> or `http://localhost:9991/help/` in
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.
2021-12-17 15:59:58 +01:00
the Zulip development environment). The help center documentation is not hosted
on ReadTheDocs, since Zulip supports running a server completely disconnected
docs: Fix minor link formatting.
2017-03-19 13:07:57 +01:00
from the Internet, and we'd like the documentation to be available in that
environment.
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
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.
2021-12-17 15:59:58 +01:00
The source for help center documentation is the Markdown files under
help-docs: Move help center documentation to top level directory. These files are not Jinja2 templates, so there's no reason that they needed to be inside `templates/zerver`. Moving them to the top level reflects their importance and also makes it feel nicer to work on editing the help center content, without it being unnecessary buried deep in the codebase.
2023-01-25 23:08:29 +01:00
`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/`.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
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.
2021-12-17 15:59:58 +01:00
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-docs: Move help center documentation to top level directory. These files are not Jinja2 templates, so there's no reason that they needed to be inside `templates/zerver`. Moving them to the top level reflects their importance and also makes it feel nicer to work on editing the help center content, without it being unnecessary buried deep in the codebase.
2023-01-25 23:08:29 +01:00
`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.
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
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.
2021-12-17 15:59:58 +01:00
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.
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
## Guide to writing help center articles
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
Writing documentation is a different form of writing than most people have
experience with.
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
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.
2021-12-17 15:59:58 +01:00
### Getting started
There are over 100 feature articles and longer guides in the
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
[Zulip help center](https://zulip.com/help/), so make the most of
the current documentation as a resource and guide as you begin.
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.
2021-12-17 15:59:58 +01:00
- Use the list on [Zulip help center home](https://zulip.com/help/)
settings: Change "Display settings" to "Preferences". This includes changing the URL to #settings/preferences, with a transparent redirect so that existing links, like the one from Welcome Bot, continue to work.
2023-06-29 15:28:38 +02:00
to find the section of the docs (e.g. Preferences, Sending
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.
2021-12-17 15:59:58 +01:00
messages, Reading messages, etc.) that relates to the new feature
you're documenting.
- Read through the existing articles in that section and pay attention
docs: Add 'Writing style' section to writing help doc tutorial. Adds a section for writing and style guidlines to the tutorial for writing help center articles. Moves the sections on 'Voice' and 'User interface' to be in the new section, and adds a section on 'Keyboard shortcuts'.
2022-06-01 22:47:11 +02:00
to the [writing style](#writing-style) used, as well as any
docs: Fix many spelling mistakes. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-08 00:13:33 +01:00
[Markdown features](#markdown-features) used to enhance the
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.
2021-12-17 15:59:58 +01:00
readability of the documentation.
- Should the feature you're documenting be added or merged into an
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
existing article?
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
help-docs: Move help center documentation to top level directory. These files are not Jinja2 templates, so there's no reason that they needed to be inside `templates/zerver`. Moving them to the top level reflects their importance and also makes it feel nicer to work on editing the help center content, without it being unnecessary buried deep in the codebase.
2023-01-25 23:08:29 +01:00
- If so, you can locate that article in `help/` and start working
on updating it with content about the new feature.
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
- 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.
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.
2021-12-17 15:59:58 +01:00
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/).
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
### 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:
docs: Add 'Writing style' section to writing help doc tutorial. Adds a section for writing and style guidlines to the tutorial for writing help center articles. Moves the sections on 'Voice' and 'User interface' to be in the new section, and adds a section on 'Keyboard shortcuts'.
2022-06-01 22:47:11 +02:00
- Maintain the format and [writing style](#writing-style) of the
current article.
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
- 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)
docs: Update `docs/documentation/` files to use channel. Updates descriptive text that refer to Zulip channels in the `docs/documentation` files to use channel instead of stream. Part of the stream to channel rename project.
2024-05-20 18:07:07 +02:00
or [channels and topics](https://zulip.com/help/streams-and-topics).
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
- 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.
urls: Simplify process to add URL redirects for documentation pages. Creates `zerver.lib.url_redirects.py` to record old and new URLs for documentation pages that have been renamed/moved and need URL redirects. This file is then used by `zproject.urls.py` to redirect links and by `zerver.test.test_urls.py` to test that all of the old URLs return a success response with a common page header/text depending on the type of redirect (help center, policy, or API). Adds a section to contributor docs on writing documentation for how to use this redirect system when renaming a help center or api documentation page. Fixes #21946. Fixes #17897.
2022-07-08 20:20:17 +02:00
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).
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
Creating robust and informative help center articles with good links
will allow users to navigate the help center much more effectively.
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.
2021-12-17 15:59:58 +01:00
### Adding a new article
If the feature you're documenting needs a new article, here are some
docs: Expand help center guide for updating existing articles. Adds a section on updating existing help center articles to the guide for writing help center documentation.
2022-01-06 18:35:30 +01:00
things to keep in mind, in addition to the points made above for
updating existing documentation:
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.
2021-12-17 15:59:58 +01:00
- Choose an existing article in the related section of the help
documentation, and copy the format, wording, style, etc. as closely
as you can.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- If the feature exists in other team chat products, check out their
docs: Update tips for writing user documentation.
2019-07-19 21:59:28 +02:00
documentation for inspiration.
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Fewer words is better than more. Many Zulip users have English as a second
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
language.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Try to put yourself in the shoes of a new Zulip user. What would you want
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
to know?
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
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.
2021-12-17 15:59:58 +01:00
- Remember to explain the purpose of the feature and give context as well
as instructions for how to use or enable it.
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- The goal of user-facing documentation is not to be comprehensive. The goal
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
is to give the right bits of information for the intended audience.
docs: Edit user documentation style guide a bit.
2017-01-17 07:12:29 +01:00
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.
2021-12-17 15:59:58 +01:00
An anti-pattern is trying to make up for bad UX by adding help center
docs: Update tips for writing user documentation.
2019-07-19 21:59:28 +02:00
documentation. It's worth remembering that for most articles, almost 100% of
the users of the feature will never read the article. Instructions for
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.
2021-12-17 15:59:58 +01:00
filling out forms, interacting with UI widgets (e.g. typeaheads), interacting
with modals, etc. should never go in the help center documentation.
docs: Fix a few grammar issues in documentation.
2021-04-13 18:04:31 +02:00
In such cases, you may be able to fix the problem by adding text in-app,
docs: Update tips for writing user documentation.
2019-07-19 21:59:28 +02:00
where the user will see it as they are interacting with the feature.
urls: Simplify process to add URL redirects for documentation pages. Creates `zerver.lib.url_redirects.py` to record old and new URLs for documentation pages that have been renamed/moved and need URL redirects. This file is then used by `zproject.urls.py` to redirect links and by `zerver.test.test_urls.py` to test that all of the old URLs return a success response with a common page header/text depending on the type of redirect (help center, policy, or API). Adds a section to contributor docs on writing documentation for how to use this redirect system when renaming a help center or api documentation page. Fixes #21946. Fixes #17897.
2022-07-08 20:20:17 +02:00
### 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
```
docs: Add 'Writing style' section to writing help doc tutorial. Adds a section for writing and style guidlines to the tutorial for writing help center articles. Moves the sections on 'Voice' and 'User interface' to be in the new section, and adds a section on 'Keyboard shortcuts'.
2022-06-01 22:47:11 +02:00
## Writing style
Below are some general style and writing conventions that should be used
as guidance when documenting Zulip's features.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
### 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
docs: Update `docs/documentation/` files to use channel. Updates descriptive text that refer to Zulip channels in the `docs/documentation` files to use channel instead of stream. Part of the stream to channel rename project.
2024-05-20 18:07:07 +02:00
used. Use **bold** for channel names, and quotation marks for topic names.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
Keep in mind that the UI may change — don’t describe it in more detail than
contributor docs: Extend help center writing style documentation.
2024-05-01 00:29:53 +02:00
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.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
docs: Clarify use of we in user docs subsystem.
2019-05-21 08:32:34 +02:00
### Voice
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.
2021-12-17 15:59:58 +01:00
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.
docs: Clarify use of we in user docs subsystem.
2019-05-21 08:32:34 +02:00
docs: Add 'Writing style' section to writing help doc tutorial. Adds a section for writing and style guidlines to the tutorial for writing help center articles. Moves the sections on 'Voice' and 'User interface' to be in the new section, and adds a section on 'Keyboard shortcuts'.
2022-06-01 22:47:11 +02:00
### Keyboard shortcuts
docs: Update tutorial section on documenting keyboard shortcuts. Updates the tutorial in "Writing help center articles: Writing style" for using `<kbd>` HTML elements when documenting keyboard shortcuts in help center articles. Also, adds section about the keyboard tip macro/syntax.
2022-08-29 17:24:32 +02:00
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>`).
docs: Add 'Writing style' section to writing help doc tutorial. Adds a section for writing and style guidlines to the tutorial for writing help center articles. Moves the sections on 'Voice' and 'User interface' to be in the new section, and adds a section on 'Keyboard shortcuts'.
2022-06-01 22:47:11 +02:00
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`).
docs: Update tutorial section on documenting keyboard shortcuts. Updates the tutorial in "Writing help center articles: Writing style" for using `<kbd>` HTML elements when documenting keyboard shortcuts in help center articles. Also, adds section about the keyboard tip macro/syntax.
2022-08-29 17:24:32 +02:00
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.
docs: Add 'Writing style' section to writing help doc tutorial. Adds a section for writing and style guidlines to the tutorial for writing help center articles. Moves the sections on 'Voice' and 'User interface' to be in the new section, and adds a section on 'Keyboard shortcuts'.
2022-06-01 22:47:11 +02:00
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
web: Move web app to ‘web’ directory. Ever since we started bundling the app with webpack, there’s been less and less overlap between our ‘static’ directory (files belonging to the frontend app) and Django’s interpretation of the ‘static’ directory (files served directly to the web). Split the app out to its own ‘web’ directory outside of ‘static’, and remove all the custom collectstatic --ignore rules. This makes it much clearer what’s actually being served to the web, and what’s being bundled by webpack. It also shrinks the release tarball by 3%. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2023-02-22 23:03:47 +01:00
change `has_mac_keyboard` in `/web/src/common.ts` to always return `True`.
docs: Add 'Writing style' section to writing help doc tutorial. Adds a section for writing and style guidlines to the tutorial for writing help center articles. Moves the sections on 'Voice' and 'User interface' to be in the new section, and adds a section on 'Keyboard shortcuts'.
2022-06-01 22:47:11 +02:00
Then when you view your documentation changes in the development environment,
the keyboard shortcuts should be rendered with Mac keys where appropriate.
docs: Update tutorial section on documenting keyboard shortcuts. Updates the tutorial in "Writing help center articles: Writing style" for using `<kbd>` HTML elements when documenting keyboard shortcuts in help center articles. Also, adds section about the keyboard tip macro/syntax.
2022-08-29 17:24:32 +02:00
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.
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.
2021-12-17 15:59:58 +01:00
## Markdown features
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
Zulip's Markdown processor allows you to include several special features in
docs: Fix some typos in documentation (most of them found and fixed by codespell). Signed-off-by: Stefan Weil <sw@weilnetz.de>
2020-03-17 13:57:10 +01:00
your documentation to help improve its readability:
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Since raw HTML is supported in Markdown, you can include arbitrary
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
HTML/CSS in your documentation as needed.
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.
2021-12-17 15:59:58 +01:00
- Code blocks allow you to highlight syntax, similar to
[Zulip's own Markdown](https://zulip.com/help/format-your-message-using-markdown).
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- Anchor tags can be used to link to headers in other documents.
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.
2021-12-17 15:59:58 +01:00
- [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
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
[tips and warnings](#tips-and-warnings).
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.
2021-12-17 15:59:58 +01:00
- Format instructions with tabs using
[Markdown tab switcher](#tab-switcher).
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
### Images
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.
2021-12-17 15:59:58 +01:00
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
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
should interact with). For instance, an image of an element should
docs: Edit user documentation style guide a bit.
2017-01-17 07:12:29 +01:00
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
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
relevant parts of the app. In addition, the screenshot should always
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
come _after_ the text that describes it, never before.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
Images are often a part of a numbered step and must be indented four
spaces to be formatted correctly.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
### Icons
third: Rename thirdparty-fonts.css for better clarity. Now it's clear that this is just legacy fontawesome styles.
2018-05-17 13:54:18 +02:00
You can refer to features in the Zulip UI by referencing their names
font-awesome: Drop support for legacy font awesome icons. We drop support for usage of `icon-vector` as base class when including icons from font awesome icons package. Now on, only icons as specified in font awesome v4.7.0 can be used in the code base.
2018-10-15 16:26:55 +02:00
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.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
contributor docs: Document bold formatting for help center inline icons. Updates "Icons" section of the "Writing help center articles" page to be consistent with current help center documentation patterns.
2023-01-20 01:15:54 +01:00
- **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`
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
### 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.
help-docs: Move help center documentation to top level directory. These files are not Jinja2 templates, so there's no reason that they needed to be inside `templates/zerver`. Moving them to the top level reflects their importance and also makes it feel nicer to work on editing the help center content, without it being unnecessary buried deep in the codebase.
2023-01-25 23:08:29 +01:00
The source for macros is the Markdown files under `help/include` in the
docs: Update macro section of user docs.
2018-09-16 09:37:31 +02:00
[main Zulip server repository](https://github.com/zulip/zulip).
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- **Administrator only feature** `{!admin-only.md!}`: Notes that the feature
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
is only available to organization administrators.
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- **Message actions** `{!message-actions.md!}`: First step to navigating to
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
the on-hover message actions.
user docs: Add the message-actions-menu macro.
2018-09-16 17:23:45 +02:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- **Message actions menu** `{!message-actions-menu.md!}`: Navigate to the
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
message actions menu.
user docs: Add the message-actions-menu macro.
2018-09-16 17:23:45 +02:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- **Save changes** `{!save-changes.md!}`: Save changes after modifying
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
organization settings.
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
docs: Update `docs/documentation/` files to use channel. Updates descriptive text that refer to Zulip channels in the `docs/documentation` files to use channel instead of stream. Part of the stream to channel rename project.
2024-05-20 18:07:07 +02:00
- **Channel actions** `{!channel-actions.md!}`: Navigate to the channel actions
docs: Clean up user-docs.md.
2018-10-10 00:00:35 +02:00
menu from the left sidebar.
user docs: Add macro for opening the compose box.
2018-09-17 00:00:37 +02:00
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- **Start composing** `{!start-composing.md!}`: Open the compose box.
user docs: Add macro for opening the compose box.
2018-09-17 00:00:37 +02:00
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
### 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.
docs: Add syntax highlighting languages to code blocks. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 07:09:04 +02:00
```md
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
!!! tip ""
help: Add newline after admonition header for Prettier compatibility. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-09-10 00:44:29 +02:00
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
If you've forgotten your password, see the
[Change your password](/help/change-your-password) page for
instructions on how to reset it.
```
docs: Update tutorial section on documenting keyboard shortcuts. Updates the tutorial in "Writing help center articles: Writing style" for using `<kbd>` HTML elements when documenting keyboard shortcuts in help center articles. Also, adds section about the keyboard tip macro/syntax.
2022-08-29 17:24:32 +02:00
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.
```
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
A **warning** is a note on what happens when there is some kind of problem.
Tips are more common than warnings.
docs: Add syntax highlighting languages to code blocks. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 07:09:04 +02:00
```md
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
!!! warn ""
help: Add newline after admonition header for Prettier compatibility. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-09-10 00:44:29 +02:00
docs: Update `docs/documentation/` files to use channel. Updates descriptive text that refer to Zulip channels in the `docs/documentation` files to use channel instead of stream. Part of the stream to channel rename project.
2024-05-20 18:07:07 +02:00
**Note:** If you attempt to input a nonexistent channel name, an error
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
message will appear.
```
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
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.
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
### Tab switcher
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
docs: Capitalize Markdown consistently. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-08-11 01:47:49 +02:00
Our Markdown processor supports easily creating a tab switcher widget
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
design to easily show the instructions for different
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.
2021-12-17 15:59:58 +01:00
[platforms](https://zulip.com/help/logging-out) in help center articles,
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
languages in API docs, etc. To create a tab switcher, write:
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
docs: Add syntax highlighting languages to code blocks. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 07:09:04 +02:00
```md
{start_tabs}
{tab|desktop-web}
# First tab's content
{tab|ios}
# Second tab's content
{tab|android}
# Third tab's content
{end_tabs}
```
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
The tab identifiers (e.g. `desktop-web` above) and their mappings to
the tabs' labels are declared in
refactor: Rename zerver.lib.bugdown to zerver.lib.markdown . This commit is first of few commita which aim to change all the bugdown references to markdown. This commits rename the files, file path mentions and change the imports. Variables and other references to bugdown will be renamed in susequent commits.
2020-06-25 15:00:33 +02:00
[zerver/lib/markdown/tabbed_sections.py][tabbed-sections-code].
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
Rename default branch to ‘main’. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-09-01 00:15:31 +02:00
[tabbed-sections-code]: https://github.com/zulip/zulip/blob/main/zerver/lib/markdown/tabbed_sections.py
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
This widget can also be used just to create a nice box around a set of
instructions
docs: Update URLs to use https://zulip.com. We're migrating to using the cleaner zulip.com domain, which involves changing all of our links from ReadTheDocs and other places to point to the cleaner URL.
2020-06-08 23:04:39 +02:00
([example](https://zulip.com/help/deactivate-your-account)) by
docs: Add documentation for tab switcher. Documentation for tab switcher added under User documentation features as a section at the bottom of "Tips and Warnings" article. Text substantially rewritten by tabbott. Fixes #12505
2019-10-27 10:29:43 +01:00
only declaring a single tab.