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.
This commit is contained in:
Lauryn Menard 2022-01-06 18:35:30 +01:00 committed by Tim Abbott
parent 784f923dda
commit 8f7f486061
1 changed files with 41 additions and 9 deletions

View File

@ -45,7 +45,7 @@ This system is designed to make writing and maintaining such documentation
highly efficient. We link to the docs extensively from the landing pages and
in-product, so it's important to keep the docs up to date.
## Guide to writing documentation
## Guide to writing help center articles
Writing documentation is a different form of writing than most people have
experience with.
@ -53,8 +53,8 @@ experience with.
### Getting started
There are over 100 feature articles and longer guides in the
[Zulip help center](https://zulip.com/help/), so use that as a resource
and guide as you begin.
[Zulip help center](https://zulip.com/help/), so make the most of
the current documentation as a resource and guide as you begin.
- Use the list on [Zulip help center home](https://zulip.com/help/)
to find the section of the docs (e.g. Display settings, Sending
@ -67,12 +67,15 @@ and guide as you begin.
readability of the documentation.
- Should the feature you're documenting be added or merged into an
existing article? If so, you can locate that article in
`templates/zerver/help` and start working on updating it with
content about the new feature.
existing article?
- If not, make a list of which articles (or guides) would be good to
link to as **Related articles** in your new feature documentation.
- 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.
Remember that real estate in the left sidebar is somewhat precious.
Minor features should rarely get their own article, and should instead
@ -83,10 +86,39 @@ can always ask in
[#documentation](https://chat.zulip.org/#narrow/stream/19-documentation)
on the [Zulip community server](https://zulip.com/development-community/).
### Updating an existing article
If the new feature you're documenting is a refinement on,
or related to, a feature that already has a dedicated help center
article, the information will be more useful and discoverable for
users as an addition to the existing article.
Here are some things to keep in mind when expanding and updating
existing help center articles:
- Maintain the format and 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.
### Adding a new article
If the feature you're documenting needs a new article, here are some
things to keep in mind:
things to keep in mind, in addition to the points made above for
updating existing documentation:
- Choose an existing article in the related section of the help
documentation, and copy the format, wording, style, etc. as closely