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

341 lines
14 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
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
`templates/zerver/help/` in the
docs: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
[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/`.
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
docs: Apply sentence single-spacing from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:53:28 +02:00
`templates/zerver/help`. If you have the Zulip development environment
docs: Correct “setup” as a verb to “set up”. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2020-08-11 01:47:54 +02:00
set up, you simply need to reload your browser on
Extract docs/user-docs.md from docs/README.md.
2017-01-17 06:58:25 +01:00
`http://localhost:9991/help/foo` to see the latest version of `foo.md`
rendered.
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/)
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
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
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 so, you can locate that article in
`templates/zerver/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.
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:
- Maintain the format and 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 [streams 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.
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.
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
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.**
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
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
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- cog (<i class="fa fa-cog"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`cog (<i class="fa fa-cog"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- down chevron (<i class="fa fa-chevron-down"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`down chevron (<i class="fa fa-chevron-down"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- eye (<i class="fa fa-eye"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`eye (<i class="fa fa-eye"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- file (<i class="fa fa-file-code-o"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`file (<i class="fa fa-file-code-o"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- filled star (<i class="fa fa-star"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`filled star (<i class="fa fa-star"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- formatting (<i class="fa fa-font"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`formatting (<i class="fa fa-font"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- menu (<i class="fa fa-bars"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`menu (<i class="fa fa-bars"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- overflow ( <i class="fa fa-ellipsis-v"></i> ) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`overflow ( <i class="fa fa-ellipsis-v"></i> ) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- paperclip (<i class="fa fa-paperclip"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`paperclip (<i class="fa fa-paperclip"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- pencil (<i class="fa fa-pencil"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`pencil (<i class="fa fa-pencil"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- pencil and paper (<i class="fa fa-pencil-square-o"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`pencil and paper (<i class="fa fa-pencil-square-o"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- plus (<i class="fa fa-plus"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`plus (<i class="fa fa-plus"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- smiley face (<i class="fa fa-smile-o"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`smiley face (<i class="fa fa-smile-o"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- star (<i class="fa fa-star-o"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`star (<i class="fa fa-star-o"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- trash (<i class="fa fa-trash-o"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`trash (<i class="fa fa-trash-o"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- video-camera (<i class="fa fa-video-camera"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`video-camera (<i class="fa fa-video-camera"></i>) icon`
docs: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- x (<i class="fa fa-times"></i>) icon —
docs: Format Markdown with Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 22:54:08 +02:00
`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.
The source for macros is the Markdown files under
`templates/zerver/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: Apply bullet style changes from Prettier. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-08-20 21:45:39 +02:00
- **Stream actions** `{!stream-actions.md!}`: Navigate to the stream 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.
```
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: Rewrite user documentation styling guide.
2017-01-16 21:38:07 +01:00
**Note:** If you attempt to input a nonexistent stream name, an error
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.