paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-03 21:43:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

documentation: Update tutorial for writing help center documentation.

Browse Source 
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.
This commit is contained in:
Lauryn Menard
2021-12-17 15:59:58 +01:00
committed by Tim Abbott
parent 048c9b99e3
commit 784f923dda
7 changed files with 122 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/documentation/overview.md
View File

@@ -2,27 +2,27 @@
Zulip has three major documentation systems:
- Developer and sysadmin documentation: Documentation for people
- **Developer and sysadmin documentation**: Documentation for people
actually interacting with the Zulip codebase (either by developing
it or installing it), and written in Markdown.
- Core website documentation: Complete webpages for complex topics,
- **Core website documentation**: Complete webpages for complex topics,
written in HTML, JavaScript, and CSS (using the Django templating
system). These roughly correspond to the documentation someone
might look at when deciding whether to use Zulip. We don't expect
to ever have more than about 10 pages written using this system.
- User-facing documentation: Our scalable system for documenting
- **User-facing documentation**: Our scalable system for documenting
Zulip's huge collection of specific features without a lot of
overhead or duplicated code/syntax, written in Markdown. We have
several hundred pages written using this system. There are 3
branches of this documentation:
- User documentation (with a target audience of individual Zulip
users),
- Integrations documentation (with a target audience of IT folks
setting up integrations), and
- API documentation (with a target audience of developers writing
code to extend Zulip).
- [Help center documentation](#help-center-documentation)
(with a target audience of individual Zulip users)
- [Integrations documentation](#integrations-documentation)
(with a target audience of IT folks setting up integrations)
- [API documentation](#api-documentation) (with a target audience
of developers writing code to extend Zulip)
These three systems are documented in detail.
@@ -89,20 +89,21 @@ unless there's a good reason, but we don't intend to migrate them,
either, since this system gives us the flexibility to express these
important elements of the product clearly.
## User facing documentation
## User-facing documentation
All of these systems use a common Markdown-based framework with
various extensions for macros and variable interpolation,
(`render_markdown_path` in the code), designed to make it convenient
to do the things one does a lot in each type of documentation.
### End user documentation
### Help center documentation
Zulip's [help center](https://zulip.com/help/) documentation is
designed to explain how the product works to end users. We aim for
this to be clear, concise, correct, and readable to nontechnical
audiences where possible. See our guide on [writing user
documentation](user.md).
audiences where possible.
See our guide on [writing help center articles](user.md).
### Integrations documentation

135
docs/documentation/user.md
View File

@@ -1,36 +1,31 @@
# User documentation
# Writing help center articles
Our goal is for Zulip to have complete, high-quality
documentation about Zulip's features and how to perform certain tasks, such
as setting up an organization.
There are two types of documents: articles about specific features, and a
handful of longer guides.
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:
The feature articles serve a few different purposes:
- Feature discovery, for someone browsing the `/help/` page, and looking at
the set of articles and guides.
- Public documentation of our feature set, for someone googling "can zulip do ..."
- Quick responses to support questions; if someone emails a Zulip admin
asking "How do I change my name?", they can reply with a link to the doc.
- Feature discovery, for someone browsing the `/help` page, and looking at
the set of titles.
- Public documentation of our feature set, for someone googling "can zulip do .."
- Canned responses to support questions; if someone emails a Zulip admin
asking "how do I change my name", they can reply with a link to the doc.
- Feature explanations for new Zulip users and admins, especially for
organization settings.
This system is designed to make writing and maintaining such documentation
highly efficient. We link to the docs extensively from the landing pages and
in-product, so it's important to keep the docs up to date.
## Editing and testing
The user documentation is available under `/help/` on any Zulip server;
Zulip help center documentation is available under `/help/` on any Zulip server;
(e.g. <https://zulip.com/help/> or `http://localhost:9991/help/` in
the Zulip development environment). The user documentation is not hosted on
ReadTheDocs, since Zulip supports running a server completely disconnected
the Zulip development environment). The help center documentation is not hosted
on ReadTheDocs, since Zulip supports running a server completely disconnected
from the Internet, and we'd like the documentation to be available in that
environment.
The source for this user documentation is the Markdown files under
The source for help center documentation is the Markdown files under
`templates/zerver/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
@@ -39,22 +34,63 @@ form `/help/foo`; with special cases for `/help/` going to `index.md` and
`/help/unknown_article` going to `missing.md` (with a 404 response). Images
are usually linked from `static/images/help/`.
This means that you can contribute to the Zulip user documentation by just
adding to or editing the collection of Markdown files under
This means that you can contribute to the Zulip help center documentation
by just adding to or editing the collection of Markdown files under
`templates/zerver/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.
## Writing documentation
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
Writing documentation is a different form of writing than most people have
experience with.
Tips for adding a new article:
### Getting started
- Find an existing article in the same section of the help documentation,
and copy the format, wording, style, etc as closely as you can.
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.
- 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
[Markdown features](#markdown-features) used to enchance the
readability of the documentation.
- Should the feature you're documenting be added or merged into an
existing article? If so, you can locate that article in
`templates/zerver/help` and start working on updating it with
content about the new feature.
- If not, make a list of which articles (or guides) would be good to
link to as **Related articles** in your new feature documentation.
Remember that real estate in the left sidebar is somewhat precious.
Minor features should rarely get their own article, and should instead
be merged into the existing help center documentation where appropriate.
If you are unsure about how and where to document the feature, you
can always ask in
[#documentation](https://chat.zulip.org/#narrow/stream/19-documentation)
on the [Zulip community server](https://zulip.com/development-community/).
### Adding a new article
If the feature you're documenting needs a new article, here are some
things to keep in mind:
- Choose an existing article in the related section of the help
documentation, and copy the format, wording, style, etc. as closely
as you can.
- If the feature exists in other team chat products, check out their
documentation for inspiration.
@@ -65,17 +101,17 @@ Tips for adding a new article:
- Try to put yourself in the shoes of a new Zulip user. What would you want
to know?
- Remember to explain the purpose of the feature and give context as well
as instructions for how to use or enable it.
- The goal of user-facing documentation is not to be comprehensive. The goal
is to give the right bits of information for the intended audience.
- Real estate in the left sidebar is somewhat precious. Minor features
should rarely get their own article.
An anti-pattern is trying to make up for bad UX by adding user
An anti-pattern is trying to make up for bad UX by adding help center
documentation. It's worth remembering that for most articles, almost 100% of
the users of the feature will never read the article. Instructions for
filling out forms, interacting with UI widgets (e.g. typeaheads),
interacting with modals, etc. should never go in user documentation.
filling out forms, interacting with UI widgets (e.g. typeaheads), interacting
with modals, etc. should never go in the help center documentation.
In such cases, you may be able to fix the problem by adding text in-app,
where the user will see it as they are interacting with the feature.
@@ -91,31 +127,40 @@ is needed. **Never identify or refer to a button by its color.**
### Voice
Do not use `we` to refer to Zulip or its creators; e.g. "Zulip also
allows .." rather than "we also allow ..". `You` is ok and used liberally.
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.
## Features
## Markdown features
Zulip's Markdown processor allows you to include several special features in
your documentation to help improve its readability:
- Since raw HTML is supported in Markdown, you can include arbitrary
HTML/CSS in your documentation as needed.
- Code blocks allow you to highlight syntax, similar to Zulip's own Markdown.
- Code blocks allow you to highlight syntax, similar to
[Zulip's own Markdown](https://zulip.com/help/format-your-message-using-markdown).
- Anchor tags can be used to link to headers in other documents.
- [Images](#images) of Zulip UI can be added to documentation.
- Inline [icons](#icons) used to refer to features in the Zulip UI.
- You can utilize [macros](#macros) to limit repeated content in the
documentation.
- You can create special highlight warning blocks using
- [Images](#images) of Zulip UI can be added to documentation, if needed.
- Inline [icons](#icons) are used to refer to features in the Zulip UI.
- Utilize [macros](#macros) to limit repeated content in the documentation.
- Create special highlight warning blocks using
[tips and warnings](#tips-and-warnings).
- You can create tabs using [Markdown tab switcher](#tab-switcher).
- Format instructions with tabs using
[Markdown tab switcher](#tab-switcher).
### Images
Images and screenshots should be included in user 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
Images and screenshots should be included in help center documentation
only if they will help guide the user in how to do something (e.g. if
the image will make it much clearer which element on the page the user
should interact with). For instance, an image of an element should
not be included if the element the user needs to interact with is the
only thing on the page, but images can be included to show the end
@@ -237,7 +282,7 @@ should be formatted as a continuation of a numbered step.
Our Markdown processor supports easily creating a tab switcher widget
design to easily show the instructions for different
[platforms](https://zulip.com/help/logging-out) in user docs,
[platforms](https://zulip.com/help/logging-out) in help center articles,
languages in API docs, etc. To create a tab switcher, write:
```md

2
docs/index.md
View File

@@ -2,7 +2,7 @@
Welcome! Zulip's documentation is split into four parts:
- [User documentation](https://zulip.com/help), for users and
- [Help center documentation](https://zulip.com/help), for users and
administrators of Zulip organizations.
- [Installation documentation](production/install.md), for
installing and maintaining a production self-hosted Zulip installation.

4
docs/subsystems/realms.md
View File

@@ -2,8 +2,8 @@
Zulip allows multiple _realms_ to be hosted on a single instance.
Realms are the Zulip codebases's internal name for what we refer to in
user documentation as an organization (the name "realm" comes from
[Kerberos](https://web.mit.edu/kerberos/)).
user-facing documentation as an organization (the name "realm" comes
from [Kerberos](https://web.mit.edu/kerberos/)).
Wherever possible, we avoid using the term `realm` in any user-facing
string or documentation; "Organization" is the equivalent term used in

2
docs/testing/testing.md
View File

@@ -66,7 +66,7 @@ Additionally, Zulip also has about a dozen smaller tests suites:
- `tools/test-documentation`: Checks for broken links in this
ReadTheDocs documentation site.
- `tools/test-help-documentation`: Checks for broken links in the
`/help` user documentation site, and related pages.
`/help/` help center documentation, and related pages.
- `tools/test-api`: Tests that the API documentation at `/api`
actually works; the actual code for this is defined in
`zerver/openapi/python_examples.py`.

12
docs/translating/german.md
View File

@@ -226,13 +226,13 @@ and there is no German equivalent, talking of "Views" is preferable in the
developer documentation and makes it easier to rely on parts of the German
_and_ parts of the English documentation.
- View - **Ansicht** (User documentation)
- View - **Ansicht** (User-facing documentation)
For the user documentation, we want to use "Ansicht" instead of "view", as
"Ansicht" provides a translated description for what you think of when hearing
"view". "Ansicht" is not desirable for the developer documentation, since it
does not emphasize the developing aspects of views (in contrast to anglicisms,
which Germans often link to IT-related definitions).
For user-facing documentation, we want to use "Ansicht" instead of "view",
as "Ansicht" provides a translated description for what you think of when
hearing "view". "Ansicht" is not desirable for the developer documentation,
since it does not emphasize the developing aspects of views (in contrast to
anglicisms, which Germans often link to IT-related definitions).
_"Ansicht" (Transifex)_

15
docs/tutorials/new-feature-tutorial.md
View File

@@ -156,10 +156,11 @@ any existing documentation that might be relevant to the new feature.
For detailed information on the kinds of documentation Zulip has, see
[Documentation](../documentation/overview.md).
**End user documentation:** You will likely need to at least update,
extend and link to `/help` articles that are related to your new
feature. See [User documentation](../documentation/user.md) for more
detailed information about writing and editing feature `/help` articles.
**Help center documentation:** You will likely need to at least update,
extend and link to `/help/` articles that are related to your new
feature. [Writing help center articles](../documentation/user.md)
provides more detailed information about writing and editing feature
`/help/` articles.
**API documentation:** A new feature will probably impact the REST API
documentation as well, which will mean updating `zerver/openapi/zulip.yaml`
@@ -686,15 +687,15 @@ important to make sure that your new feature is well documented.
This example feature adds new functionality that requires messages to
have topics if the setting is enabled. A recommended way to document
this feature would be to update and/or augment Zulip's existing
[end user documentation (Help Center)](https://zulip.com/help/)
to reflect your changes and additions.
[help center documentation](https://zulip.com/help/) to reflect your
changes and additions.
At the very least, this will involve modifying (or adding) a Markdown
file documenting the feature to `templates/zerver/help/` in the main
Zulip server repository, where the source for Zulip's end user
documentation is stored. Details about writing, editing and testing
these Markdown files can be found in:
[User documentation](../documentation/user.md).
[Writing help center articles](../documentation/user.md).
Also, new features will often impact Zulip's REST API documentation,
which is found in `zerver/openapi/zulip.yaml`. You may have noticed