mirror of https://github.com/zulip/zulip.git
docs: Update documentation styling guide with new guidelines.
This commit is contained in:
synicalsyntax
parent
88ec999cf3
commit
c9eaf67c78
276
docs/README.md
276
docs/README.md
|
|
@ -132,7 +132,219 @@ below.
|
|||
[the python-markdown docs on this extension](https://pythonhosted.org/Markdown/extensions/admonition.html)
|
||||
for details on how this extension works; essentially the value
|
||||
`warn` or `tip` is an extra CSS class added to the admonition.
|
||||
#### Macros
|
||||
**Macros** are elements in the format of `{!macro.md!}` that insert common phrases
|
||||
and steps at the location of the macros.
|
||||
##### **Administration** `{!admin.md!}` macro
|
||||
* **About:** Links to the **Edit Administrator Settings** documentation. Usually
|
||||
preceded by the [**Go to the** macro](#go-to-the-go-to-the-md-macro) and a link to a
|
||||
particular section on the **Administration** page.
|
||||
* **Contents:**
|
||||
```.md
|
||||
tab of the [Administration](/help/edit-administrator-settings) page.
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!go-to-the.md!} [Organization Settings](/#administration/organization-settings)
|
||||
{!admin.md!}
|
||||
```
|
||||
```.md
|
||||
1. Go to the [OrganizationSettings](/#administration/organization-settings) tab of the
|
||||
[Administration](/help/edit-administrator-settings) page.
|
||||
```
|
||||
##### **All streams** `{!all-sreams.md!}` macro
|
||||
* **About:** Explains how to view all streams in the organization on the
|
||||
**Subscriptions** page. Usually formatted as a tip and preceded by the
|
||||
[**Subscriptions** macro](#subscriptions-subscriptions-md-macro) and the
|
||||
[**Filter streams** macro](#filter-streams-filter-streams-md-macro).
|
||||
* **Contents:**
|
||||
```.md
|
||||
If you wish to see streams that you aren't subscribed to, click on the
|
||||
**All Streams** tab; the tab will turn gray upon doing so.
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!subscriptions.md!}
|
||||
{!filter-streams.md!}
|
||||
!!! tip ""
|
||||
{!all-streams.md!}
|
||||
```
|
||||
```.md
|
||||
1. [Find the relevant stream](/help/browse-and-join-streams#browse-streams) on the
|
||||
[Subscriptions](/#subscriptions) page. You can search for specific streams by entering the
|
||||
name of the stream in the **Filter Streams** input.
|
||||
!!! tip ""
|
||||
If you wish to see streams that you aren't subscribed to, click on the
|
||||
**All Streams** tab; the tab will turn gray upon doing so.
|
||||
```
|
||||
##### **Down chevron** `{!down-chevron.md!}` macro
|
||||
* **About:** Instructs readers to click on the down chevron (<i class="fa
|
||||
fa-chevron-down"></i>) icon to reveal an actions dropdown; usually preceded by
|
||||
an command, such as the [**Message actions**
|
||||
macro](#message-actions-message-actions-md-macro).
|
||||
* **Contents:**
|
||||
```.md
|
||||
down chevron (<i class="icon-vector-chevron-down"></i>) icon to reveal an actions dropdown.
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!message-actions.md!}
|
||||
{!down-chevron.md!}
|
||||
```
|
||||
```.md
|
||||
1. Hover over a message to replace the message's timestamp with its message
|
||||
actions, represented by three icons. From the icons that appear, select the
|
||||
down chevron (<i class="icon-vector-chevron-down"></i>) icon to reveal an actions dropdown.
|
||||
```
|
||||
##### **Go to the** `{!go-to-the.md}` macro
|
||||
* **About:** Usually precedes the [**Settings** macro](#settings-settings-md-macro)
|
||||
or the [**Administration** macro](#administration-admin-md-macro). Transforms
|
||||
following content into a step.
|
||||
* **Contents:**
|
||||
```.md
|
||||
1. Go to the
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!go-to-the.md!} [Notifications](/#settings/notifications)
|
||||
{!settings.md!}
|
||||
```
|
||||
```.md
|
||||
1. Go to the [Notifications](/#settings/notifications) tab on the
|
||||
[Settings](/help/edit-settings) page.
|
||||
```
|
||||
##### **Filter streams** `{!filter-streams.md!}` macro
|
||||
* **About:** Explains how to search for specific streams in the
|
||||
**Subscriptions** page using the **Filter Streams** input. Usually preceded by
|
||||
the [**Subscriptions** macro](#subscriptions-subscriptions-md-macro).
|
||||
* **Contents:**
|
||||
```.md
|
||||
You can search for specific streams by entering the name of the stream in
|
||||
the **Filter Streams** input.
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!subscriptions.md!}
|
||||
{!filter-streams.md!}
|
||||
```
|
||||
```.md
|
||||
1. [Find the relevant stream](/help/browse-and-join-streams#browse-streams) on the
|
||||
[Subscriptions](/#subscriptions) page. You can search for specific streams by entering the
|
||||
name of the stream in the **Filter Streams** input.
|
||||
```
|
||||
##### **Message actions** `{!message-actions.md!}` macro
|
||||
* **About:** Explains how to view the actions of message. Usually followed by an instruction
|
||||
to click a specific icon, such as the [**Down chevron** macro](#down-chevron-down-chevron-md-macro).
|
||||
* **Contents:**
|
||||
```.md
|
||||
1. Hover over a message to replace the message's timestamp with its message
|
||||
actions, represented by three icons. From the icons that appear, select the
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!message-actions.md!}
|
||||
{!down-chevron.md!}
|
||||
```
|
||||
```.md
|
||||
1. Hover over a message to replace the message's timestamp with its message
|
||||
actions, represented by three icons. From the icons that appear, select the
|
||||
down chevron (<i class="icon-vector-chevron-down"></i>) icon to reveal an actions dropdown.
|
||||
```
|
||||
##### **Settings** `{!settings.md!}` macro
|
||||
* **About:** Links to the **Edit Settings** documentation. Usually preceded by
|
||||
the [**Go to the** macro](#go-to-the-go-to-the-md-macro) and a link to a
|
||||
particular section on the **Settings** page.
|
||||
* **Contents:**
|
||||
```.md
|
||||
tab on the [Settings](/help/edit-settings) page.
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!go-to-the.md!} [Notifications](/#settings/notifications)
|
||||
{!settings.md!}
|
||||
```
|
||||
```.md
|
||||
1. Go to the [Notifications](/#settings/notifications) tab on the
|
||||
[Settings](/help/edit-settings) page.
|
||||
```
|
||||
##### **Stream actions** `{!stream-actions.md!}` macro
|
||||
* **About:** Explains how to view the actions of stream. Usually followed by the an
|
||||
instruction and the [**Down chevron** macro](#down-chevron-down-chevron-md-macro).
|
||||
* **Contents:**
|
||||
```.md
|
||||
1. On the left sidebar in the **Streams** section, hover over a stream to reveal
|
||||
a down chevron (<i class="icon-vector-chevron-down"></i>) icon to the right of
|
||||
the stream name.
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!stream-actions.md!}
|
||||
|
||||
1. Click on the {!down-chevron.md!}
|
||||
```
|
||||
```.md
|
||||
1. On the left sidebar in the **Streams** section, hover over a stream to reveal
|
||||
a down chevron (<i class="icon-vector-chevron-down"></i>) icon to the right of
|
||||
the stream name.
|
||||
|
||||
2. Click on the down chevron (<i class="icon-vector-chevron-down"></i>)
|
||||
icon to reveal an actions dropdown.
|
||||
```
|
||||
##### **Stream Settings** `{!stream-settings.md!}` macro
|
||||
* **About:** Notifies readers about the changes in the **Subscriptions** page when a stream is selected; usually followed by an instruction.
|
||||
* **Contents:**
|
||||
```.md
|
||||
the right side of the [Subscriptions](/#subscriptions) page, labeled
|
||||
**Stream Settings**, will now display the selected stream's settings.
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
1. Click on the stream you want to edit; {!stream-settings.md!}
|
||||
```
|
||||
```.md
|
||||
1. Click on the stream you want to edit; the right side of the
|
||||
[Subscriptions](/#subscriptions) page, labeled **Stream Settings**, will
|
||||
now display the selected stream's settings.
|
||||
```
|
||||
##### **Stream Settings scroll** `{!stream-settings.md!}` macro
|
||||
* **About:** Instructs readers to scroll down to a particular section on the
|
||||
**Subscriptions** page after making sure their cursors are hovering above the
|
||||
**Streams Settings** section.
|
||||
* **Contents:**
|
||||
```.md
|
||||
1. After making sure that your cursor is hovering over the **Streams Settings**
|
||||
section, scroll down to the
|
||||
```
|
||||
* **Example usage and rendering:**
|
||||
```.md
|
||||
{!stream-settings-scroll.md!} **Stream membership** section. This section
|
||||
shows the usernames and emails of all users that are currently subscribed to the
|
||||
selected stream.
|
||||
```
|
||||
```.md
|
||||
1. After making sure that your cursor is hovering over the **Streams Settings**
|
||||
section, scroll down to the **Stream membership** section. This section
|
||||
shows the usernames and emails of all users that are currently subscribed to the
|
||||
selected stream.
|
||||
```
|
||||
##### **Subscriptions** `{!subscriptions.md!}` macro
|
||||
* **About:** Used in documentation that direct users to the **Subscriptions** page.
|
||||
Often followed by the [**Filter streams** macro](#filter-streams-filter-streams-md-macro).
|
||||
* **Contents:**
|
||||
```.md
|
||||
1. [Find the relevant stream](/help/browse-and-join-streams#browse-streams) on
|
||||
the [Subscriptions](/#subscriptions) page.
|
||||
```
|
||||
* Standard usage and rendering:
|
||||
```.md
|
||||
{!subscriptions.md!}
|
||||
{!filter-streams.md!}
|
||||
```
|
||||
```.md
|
||||
1. [Find the relevant stream](/help/browse-and-join-streams#browse-streams) on the
|
||||
[Subscriptions](/#subscriptions) page. You can search for specific streams by entering the
|
||||
name of the stream in the **Filter Streams** input.
|
||||
```
|
||||
### Style guide
|
||||
|
||||
* Names of buttons, fields, etc. should be **bolded** (e.g. **Settings**
|
||||
|
|
@ -153,8 +365,40 @@ indenting them.
|
|||
than is needed.
|
||||
* Never refer specifically to button colors.
|
||||
|
||||
* All icons should be referenced by their names and images within parentheses, e.g.: "between the **A**
|
||||
() and **eye** () icons"
|
||||
* All icons should be referenced by their names and their [FontAwesome](http://fontawesome.io)
|
||||
(version 3.0.2) text icons within parentheses.
|
||||
* cog (<i class="fa fa-cog"></i>) icon — `cog (<i
|
||||
class="icon-vector-cog"></i>) icon`
|
||||
* down chevron (<i class="fa fa-chevron-down"></i>) icon —
|
||||
`down chevron (<i class="icon-vector-chevron-down"></i>) icon`
|
||||
* eye (<i class="fa fa-eye"></i>) icon — `eye (<i
|
||||
class="icon-vector-eye-open"></i>) icon`
|
||||
* file (<i class="fa fa-file-text-o"></i>) icon — `file (<i
|
||||
class="icon-vector-file-text-alt"></i>) icon`
|
||||
* filled star (<i class="fa fa-star"></i>) icon —
|
||||
`filled star (<i class="icon-vector-star"></i>) icon`
|
||||
* formatting (<i class="fa fa-font"></i>) icon —
|
||||
`formatting (<i class="icon-vector-font"></i>) icon`
|
||||
* menu (<i class="fa fa-bars"></i>) icon — `menu (<i
|
||||
class="icon-vector-reorder"></i>) icon`
|
||||
* overflow ( <i class="fa fa-ellipsis-v"></i> ) icon —
|
||||
`overflow ( <i class="icon-vector-ellipsis-verical"></i> ) icon`
|
||||
* paperclip (<i class="fa fa-paperclip"></i>) icon —
|
||||
`paperclip (<i class="icon-vector-paperclip"></i>) icon`
|
||||
* pencil (<i class="fa fa-pencil"></i>) icon —
|
||||
`pencil (<i class="icon-vector-pencil"></i>) icon`
|
||||
* pencil and paper (<i class="fa fa-pencil-square-o"></i>) icon —
|
||||
`pencil and paper (<i class="icon-vector-edit"></i>) icon`
|
||||
* plus (<i class="fa fa-plus"></i>) icon —
|
||||
`plus (<i class="icon-vector-plus"></i>) icon`
|
||||
* smiley face (<i class="fa fa-smile-o"></i>) icon —
|
||||
`smiley face (<i class="icon-vector-smile"></i>) icon`
|
||||
* star (<i class="fa fa-star-o"></i>) icon —
|
||||
`star (<i class="icon-vector-star-empty"></i>) icon`
|
||||
* trash (<i class="fa fa-trash-o"></i>) icon —
|
||||
`trash (<i class="icon-vector-trash"></i>) icon`
|
||||
* x (<i class="fa fa-times"></i>) icon —
|
||||
`x (<i class="icon-vector-remove"></i>) icon`
|
||||
|
||||
* Guidelines for **tips** and **warnings**:
|
||||
|
||||
|
|
@ -205,31 +449,3 @@ indenting them.
|
|||
button and **Forgot your password?** link.
|
||||
|
||||
|
||||
|
||||
* Standard formulas for directing users to commonly used pages:
|
||||
|
||||
* There is a macro for directing users to the **Subscriptions** page:
|
||||
`{!subscriptions.md!}`
|
||||
|
||||
* The **Go to the** macro (`{!go-to-the.md}`) usually precedes the
|
||||
**Settings** and **Administration** macros. This macro transforms the
|
||||
following content into a step.
|
||||
|
||||
* The **Settings** macro (`{!settings.md!}`) directs users to the **Settings**
|
||||
page. It is usually preceded by the **Go to the** macro and a link to a
|
||||
particular section in the **Settings** page.
|
||||
|
||||
* The **Administration** macro (`{!admin.md!}`) directs users to the
|
||||
**Administration** page. It is usually preceded by the **Go to the** macro and
|
||||
a link to a particular section in the **Administration** page.
|
||||
|
||||
* Example:
|
||||
```.md
|
||||
{!go-to-the.md!} [Notifications](/#settings/notifications)
|
||||
{!settings.md!}
|
||||
```
|
||||
renders as:
|
||||
```.md
|
||||
1. Go to the [Notifications](/#settings/notifications) tab on the
|
||||
[Settings](/help/edit-settings) page.
|
||||
```
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 1.5 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 1.5 KiB |
|
|
@ -24,10 +24,10 @@ the **Save** button to save the changes you made to your message.
|
|||
Depending on your organization settings, Zulip may be configured with a time
|
||||
limit within which you may edit a message (e.g. 10 minutes). As soon as that
|
||||
limit has passed, the pencil (<i class="icon-vector-pencil"></i>) icon
|
||||
changes to a file () icon.
|
||||
changes to a file (<i class="icon-vector-file-text-alt"></i>) icon.
|
||||
|
||||
!!! tip ""
|
||||
Clicking on () icon will allow you to
|
||||
Clicking on (<i class="icon-vector-file-text-alt"></i>) icon will allow you to
|
||||
view the [Markdown source](/help/view-the-markdown-source-of-a-message) or
|
||||
[change the topic](/help/change-the-topic-of-a-message) of your message.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,3 @@
|
|||
1. On the left sidebar in the **Streams** section, hover over a streams to
|
||||
reveal a down chevron (<i class="icon-vector-chevron-down"></i>)
|
||||
icon to the right of the stream name.
|
||||
1. On the left sidebar in the **Streams** section, hover over a stream to reveal
|
||||
a down chevron (<i class="icon-vector-chevron-down"></i>) icon to the right of
|
||||
the stream name.
|
||||
|
|
|
|||
Loading…
Reference in New Issue