diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/install/Amazon-Elastic-Beanstalk.md | 45 | ||||
| -rw-r--r-- | doc/install/SMTP-Email-Setup.md | 12 | ||||
| -rw-r--r-- | doc/integrations/webhooks/Incoming-Webhooks.md | 6 | ||||
| -rw-r--r-- | doc/integrations/webhooks/Outgoing-Webhooks.md | 2 | ||||
| -rw-r--r-- | doc/process/documentation-guidelines.md | 185 |
5 files changed, 221 insertions, 29 deletions
diff --git a/doc/install/Amazon-Elastic-Beanstalk.md b/doc/install/Amazon-Elastic-Beanstalk.md index 0416b67ea..8738ab3ac 100644 --- a/doc/install/Amazon-Elastic-Beanstalk.md +++ b/doc/install/Amazon-Elastic-Beanstalk.md @@ -1,27 +1,26 @@ ## AWS Elastic Beanstalk Setup (Docker) +These instructions will guide you through the process of setting up Mattermost for product evaluation using an EBS Docker single-container application using [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.1/Dockerrun.aws.zip). -1. Create a new Elastic Beanstalk Docker application using the [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.0/Dockerrun.aws.zip) file provided. - 1. From the AWS console select Elastic Beanstalk. - 2. Select "Create New Application" from the top right. - 3. Name the application and press next. - 4. Select "Create a web server" environment. - 5. If asked, select create an IAM role and instance profile and press next. - 6. For predefined configuration select under Generic: Docker. For environment type select single instance. - 7. For application source, select upload your own and upload Dockerrun.aws.zip from [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.0/Dockerrun.aws.zip). Everything else may be left at default. - 8. Select an environment name, this is how you will refer to your environment. Make sure the URL is available then press next. - 9. The options on the additional resources page may be left at default unless you wish to change them. Press Next. - 10. On the configuration details place. Select an instance type of t2.small or larger. - 11. You can set the configuration details as you please but they may be left at their defaults. When you are done press next. - 12. Environment tags my be left blank. Press next. - 13. You will be asked to review your information. Press Launch. - -4. Try it out! - 14. Wait for beanstalk to update the environment. - 15. Try it out by entering the domain of the form \*.elasticbeanstalk.com found at the top of the dashboard into your browser. You can also map your own domain if you wish. - - - ### (Recommended) Enable Email - The default single-container Docker instance for Mattermost is designed for product evaluation, and sets `ByPassEmail=true` so the product can run without enabling email, when doing so maybe difficult. +1. From your [AWS console]( https://console.aws.amazon.com/console/home) select **Elastic Beanstalk** under the Compute section. +2. Select **Create New Application** from the top right. +3. Name your Elastic Beanstalk application and click **Next**, +4. Select **Create web server** on the New Enviroment page. +5. If asked, select **Create an IAM role and instance profile**, then click **Next**. +6. On the Enviroment Type page, + 1. Set Predefined Configuration to **Docker** under the generic heading in the drop-down list. + 2. Set Environment Type to **Single instance** in the drop-down list. + 3. Click **Next**. +7. For Application Source, select **Upload your own** and upload the [Dockerrun.aws.zip](https://github.com/mattermost/platform/raw/master/docker/1.1/Dockerrun.aws.zip) file, then click **Next**. +8. Type an Environment Name and URL. Make sure the URL is available by clicking **Check availability**, then click **Next**. +9. The options on the Additional Resources page may be left at default unless you wish to change them. Click **Next**. +10. On the Configuration Details page, + 1. Select an Instance Type of **t2.small** or larger. + 2. The remaining options may be left at their default values unless you wish to change them. Click **Next**. +11. Environment tags may be left blank. Click **Next**. +12. You will be asked to review your information, then click **Launch**. +14. It may take a few minutes for beanstalk to launch your environment. If the launch is successful, you will see a see a large green checkmark and the Health status should change to “Green”. +15. Test your environment by clicking the domain link next to your application name at the top of the dashboard. Alternatively, enter the domain into your browser in the form `http://<your-ebs-application-url>.elasticbeanstalk.com`. You can also map your own domain if you wish. If everything is working correctly, the domain should navigate you to the Mattermost signup page. Enjoy exploring Mattermost! - To see the product's full functionality, [enabling SMTP email is recommended](SMTP-Email-Setup.md). +### (Recommended) Enable Email +The default single-container Docker instance for Mattermost is designed for product evaluation, and sets `SendEmailNotifications=false` so the product can function without enabling email. To see the product's full functionality, [enabling SMTP email is recommended](SMTP-Email-Setup.md). diff --git a/doc/install/SMTP-Email-Setup.md b/doc/install/SMTP-Email-Setup.md index bb57d95ba..7d9beae89 100644 --- a/doc/install/SMTP-Email-Setup.md +++ b/doc/install/SMTP-Email-Setup.md @@ -52,10 +52,18 @@ To enable email, configure an SMTP email service as follows: * Set **Connection Security** to **(empty)** ##### Gmail -* Information needed +* Set **SMTP Username** to **your_email@gmail.com** +* Set **SMTP Password** to **your_password** +* Set **SMTP Server** to **smtp.gmail.com** +* Set **SMTP Port** to **587** +* Set **Connection Security** to **TLS** ##### Office 365 -* Information needed +* Set **SMTP Username** to **Office 365 username** +* Set **SMTP Password** to **Office 365 password** +* Set **SMTP Server** to **smtp.office365.com** +* Set **SMTP Port** to **587** +* Set **Connection Security** to **TLS** ##### Hotmail * Set **SMTP Username** to **your_email@hotmail.com** diff --git a/doc/integrations/webhooks/Incoming-Webhooks.md b/doc/integrations/webhooks/Incoming-Webhooks.md index b10b6e342..b5ae0fde2 100644 --- a/doc/integrations/webhooks/Incoming-Webhooks.md +++ b/doc/integrations/webhooks/Incoming-Webhooks.md @@ -90,9 +90,9 @@ As mentioned above, Mattermost makes it easy to take integrations written for Sl To see samples and community contributions, please visit <http://mattermost.org/webhooks>. -#### Known Issues +#### Known Issues in v1.1 - The `attachments` payload used in Slack is not yet supported -- Overriding of usernames does not yet apply to notifications +- Overriding of usernames does not yet apply to notifications (fixed on master) - Cannot supply `icon_emoji` to override the message icon -- Webhook UI fails when connected to deleted channel +- Webhook UI fails when connected to deleted channel (fixed on master) diff --git a/doc/integrations/webhooks/Outgoing-Webhooks.md b/doc/integrations/webhooks/Outgoing-Webhooks.md index abe26ceae..008245715 100644 --- a/doc/integrations/webhooks/Outgoing-Webhooks.md +++ b/doc/integrations/webhooks/Outgoing-Webhooks.md @@ -114,7 +114,7 @@ As mentioned above, Mattermost makes it easy to take integrations written for Sl To see samples and community contributions, please visit <http://mattermost.org/webhooks>. -#### Known Issues +#### Known Issues in v1.1 - Overriding of usernames does not yet apply to notifications - Cannot supply `icon_emoji` to override the message icon diff --git a/doc/process/documentation-guidelines.md b/doc/process/documentation-guidelines.md new file mode 100644 index 000000000..f37f0c5fc --- /dev/null +++ b/doc/process/documentation-guidelines.md @@ -0,0 +1,185 @@ +# Documentation Conventions + +The most important thing about documentation is getting it done and out to the community. + +After that, we can work on upgrading the quality of documentation. The below chart summarizes the different levels of documentation and how the quality gates are applied. + +_Note: Documentation Guidelines are new, and iterating. Documentation has started to balloon and this is our attempt at reducing ambiguity and increasing consistency, but the conventions here are very open to discussion._ + +| Stars | Benchmark | Timeline | +|:-------------|:--------------------------------|:--------------------------------| +| 1 | Documentation is correct. | First draft checked in by developer. Okay to ship in first release of new feature. | +| 2 | Documentation a) follows all objective formatting criteria, b) is tested by someone other than the author, c) satisfies above. | First edit under objective rules. Required before second release cycle with this feature included. | +| 3 | Documentation a) follows all subjective style criteria, b) is reviewed and edited by someone who has previously authored 3-star documentation, and c) satisfies above. | Second edit under subjective rules. Required before third release cycle with this feature included | +| 4 | Documentation a) has received at least 1 edit due to user feedback, b) has received at least one unprompted compliment from user community on quality, c) satisfies above. | Additional edits to refine documentation based on user feedback | + +## 1-Star Requirements: Correctness + +### List precise dependencies + +1. Be explicit about what specific dependencies have been tested as part of an installation procedure. +2. Be explicit about assumptions of compatibility on systems that have not been tested. +3. Do not claim the system works on later versions of a platform if backwards compatibility is not a priority for the dependency (It's okay to say Chrome version 43 and higher, but not Python 2.6 and higher, because Python 3.0 is explicitly incompatible with previous versions). + +#### Correct + +---- +This procedure works on an Ubuntu 14.04 server with Python 2.6 installed and should work on compatible Linux-based operating systems and compatible versions of Python. + +---- +#### Incorrect + +---- +This procedure works on Linux servers running Python. + +also: + +This procedure works on Linux servers running Python 2.6 and higher. + +---- +## 2-Star Requirements: Objective Formatting Checklist + +### Use headings + +Headings in markdown provide anchors that can be used to easily reference sub-sections of long pieces of documentation. This is preferrable to just numbering sections without headings. + +##### Correct: + +---- +##### Step 1: Add a heading +This makes things easier to reference via hyperlinks +##### Step 2: Link to headings +So things are eariser to find + +---- +##### Incorrect: + +---- +**Step 1: Add a heading** +This makes things easier to reference via hyperlinks +**Step 2: Link to headings** +So things are eariser to find +---- + +### Use appropriate heading case + +Cases in headings may vary depending on usage. + +#### When to use Title Case + +H1, H2, H3 headings should be "Title Case" and less than four words, except if a colon is used, then four words per segment separated by the colon. + +These large headings are typically shorter and help with navigating large documents + +#### When to use sentence case + +H3, H4, H5 headings should be "Sentence case" and can be any length. + +These headers are smaller and used to summarize sections. H3 can be considered either a large or small heading. + +These conventions are new, so there's flexibility around them, when you're not sure, consider the convention here as default. + +### One instruction per line + +It's easy to miss instructions when they're compounded. Have only one instruction per line, so documentation looks more like a checklist. + +A support person should be able to say "Did you complete step 7?" instead of "Did you complete the second part of step 7 after doing XXX?" + +##### Correct: + +---- + +6. For **Predefined configuration** look under **Generic** and select **Docker**. + 7. For **Environment type** select **Single instance** + +---- + +##### Incorrect: + +---- + +6. For **Predefined configuration** look under **Generic** and select **Docker**. For **Environment type** select **Single instance** + +---- + +### Lists end without periods + +Sentences within bullet points or numbered lists should end in normal punctuation. The sentence or fragment at the end of a bullet point should not have a period. + +##### Correct + +---- +- This is a sentence within a bullet point. This is the end of a bullet point without a period + +---- +##### Incorrect + +---- +- This is an incorrect ending of a bullet point with a period. + +---- +### Avoid Passive Phrases + +Examples of passive phrases include "have", "had", "was", "can be", "has been" and documentation is shorter and clearer without them. + +##### Correct + +---- +This software **runs** on any server that supports Python. + +---- +##### Incorrect + +---- +This software **can be run** on any server that supports Python. + +---- +## 3-Star Requirements: Subjective Style Guidelines + +### Be Concise + +Try to use fewer words when possible. + +##### Correct: + +---- +This integration posts [issue](http://doc.gitlab.com/ee/web_hooks/web_hooks.html#issues-events), [comment](http://doc.gitlab.com/ee/web_hooks/web_hooks.html#comment-events) and [merge request](http://doc.gitlab.com/ee/web_hooks/web_hooks.html#merge-request-events) events from a GitLab repository into specific Mattermost channels by formatting output from [GitLab's outgoing webhooks](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/web_hooks/web_hooks.md) to [Mattermost's incoming webhooks](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Incoming-Webhooks.md). + +---- +##### Incorrect: + +---- +This integration makes use of GitLab's outgoing webhooks and Mattermost's incoming webhooks to post GitLab events into Mattermost. You can find GitLab's outgoing webhooks described [here](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/web_hooks/web_hooks.md) and Mattermost's incoming webhooks described [here](https://github.com/mattermost/platform/blob/master/doc/integrations/webhooks/Incoming-Webhooks.md). + +---- + +### Use appropriate emphasis + +Mention Clickable Controls in **Bold**, Sections and Setting Names in *Italics*, and Key Strokes in `pre-formatted text`. + +To make it clear and consistent across documentation on how we describe controls that a user is asked to manipulate, we have a number of guidelines: + +**Bold** +- Please **bold** the names of controls you're asking users to click. The text that is bolded should match the label of the control in the user interface. Do not format these references with _italics_, ALL-CAPS or `pre-formatted text`. +- Use `>` to express a series of clicks, for example clicking on **Button One** > **Button Two** > **Button Three**. +- If a button might be difficult to find, give a hint about its location _before_ mentioning the name of the control (this helps people find the hint before they start searching, if the see the name of the button first, they might not continue reading to find the hint before starting to look). + +***Italics*** +- Please *italicize* setting names or section headings that identify that the user is looking in the correct area. The text that is italicized should match the name of the setting or section in the user interface. +- It is helpful to use italics to guide the user to the correct area before mentioning a clickable action in bold. + +**`pre-formatted text`** +- Please use `pre-formatted text` to identify when a user must enter key strokes or paste text into an input box. + +#### Correct + +---- +Type `mattermost-integration-giphy` in the *repo-name* field, then click **Search** and then the **Connect** button once Heroku finds your repository + +---- +#### Incorrect + +---- +Type "mattermost-integration-giphy" in the **repo-name** field, then click Search and then the *Connect* button once Heroku finds your repository + +---- |