docs: Update documentation styling guide with new guidelines.

2025-11-04 05:53:43 +00:00 · 2017-01-05 19:26:18 -08:00
parent 88ec999cf3
commit c9eaf67c78
5 changed files with 251 additions and 35 deletions
--- a/docs/README.md
+++ b/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**
-(![A](/images/formatting.png)) and **eye** (![eye](/images/eye.png)) 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.

      ![Zulip sign in Google](/images/signin-google.png)
-
-* 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.
-      ```
--- a/docs/images/eye.png
+++ b/docs/images/eye.png
--- a/docs/images/formatting.png
+++ b/docs/images/formatting.png
--- a/templates/zerver/help/edit-or-delete-a-message.md
+++ b/templates/zerver/help/edit-or-delete-a-message.md
@@ -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 (![file](/static/images/help/file.png)) icon.
+changes to a file (<i class="icon-vector-file-text-alt"></i>) icon.

 !!! tip ""
-    Clicking on (![file](/static/images/help/file.png)) 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.

--- a/templates/zerver/help/include/stream-actions.md
+++ b/templates/zerver/help/include/stream-actions.md
@@ -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.