Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

WIP: First time user docs #643

Closed
wants to merge 6 commits into from

Conversation

@JeffSchering
Copy link
Contributor

JeffSchering commented Nov 4, 2016

These are a couple of docs that are written with the new style guide in mind. They should fit right in to the existing docs, although there's a bit of overlap. They're best viewed in the processed-by-Sphinx form rather than in the format as displayed by GitHub. That is, it's best to clone or download and build rather than view the repo on GitHub.

@esethna esethna changed the title WIP: First time user docs First time user docs Nov 28, 2016
@esethna

This comment has been minimized.

Copy link
Member

esethna commented Dec 1, 2016

Hey @JeffSchering, sorry for the delayed review on this, PM team is planning to do a group review tomorrow afternoon.

@esethna

This comment has been minimized.

Copy link
Member

esethna commented Dec 6, 2016

Hi @JeffSchering, this guide is much needed, thanks again for this contribution!

I've compiled a review below, I'm happy to submit a PR against this branch for the changes or feel free to ping me to discuss anything if you'd prefer to work on them yourself? Please let me know how you'd like to proceed?

@@ -0,0 +1,27 @@
=====================
Updating your profile
=====================

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Sounds like we are leaning toward the monolith style of docs? If so, I'd propose we merge this doc with the creating an account doc since that seems like it fits with the workflow.

This comment has been minimized.

Copy link
@JeffSchering

JeffSchering Dec 6, 2016

Author Contributor

Yep.

@@ -0,0 +1,53 @@
=================================================
Creating an account and signing in the first time

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Propose maybe calling this doc "Creating an Account" so it fits better with the naming convension of the rest of the docs in this section?

image

This comment has been minimized.

Copy link
@JeffSchering

JeffSchering Dec 6, 2016

Author Contributor

This is what it looks like when built:

image

This is due to the way it's included in the top-level doc:
Creating an account </help/getting-started/creating-an-account.rst>

This comment has been minimized.

Copy link
@esethna

esethna Dec 7, 2016

Member

Oh great, but can we use title case here? ie Creating an Account

This comment has been minimized.

Copy link
@JeffSchering

JeffSchering Dec 8, 2016

Author Contributor

I'd like to reserve title case for topic or page titles, and use sentence case for sub sections.

Note also that this file was created when the style guide was in its very early phase, so I still need to make some adjustments for that.

- If your administrator sent you instructions, use those instructions.
- If you are not able to create an account using these instructions, contact your administrator.

On the account creation page, you must enter the following information:

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

I think we should add a section here about the options for signing up other than email. Sometimes the system could have more than one account creation method enabled, then the user should follow instructions from their System Admin. Open to suggestions to build on this idea, but I think the following info is important:

  1. Email and Password
  • What you have here
  1. Single-Sign-On Services
  • Mention that accounts are created the first time you sign in.
  • Username is automatically generated but can be changed in Account Settings for certain account types.
  • Options for SSO are GitLab, LDAP, SAML, Office 365 and Google depending on what the sys admin has enabled.

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Also I'd propose this section has a header, perhaps "Account Creation Methods"

This comment has been minimized.

Copy link
@JeffSchering

JeffSchering Dec 6, 2016

Author Contributor

The info that you're talking about in 2. is on this page: https://docs.mattermost.com/help/getting-started/signing-in.html

This comment has been minimized.

Copy link
@esethna

esethna Dec 7, 2016

Member

In my mind this is different information. On the Signing in page we dont mention that accounts are created the first time you sign in. We also dont mention how the username gets created in each case. We should either add that info to the "signing in" page, or make room for it here. I think it makes sense to have it here so people understand that there are other methods to create an account other than email. Open to discussion,

This comment has been minimized.

Copy link
@JeffSchering

JeffSchering Dec 8, 2016

Author Contributor

Can you take a look at this forum post? http://forum.mattermost.org/t/request-feedback-and-accuracy-check-on-a-getting-started-topic/2468/3

It contains some thoughts related to structure and content of this section.

On the account creation page, you must enter the following information:

email address
Enter the address that you want to use for signing in, receiving notifications, resetting passwords, and receiving your account confirmation email.

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Propose using a more active voice to follow the guide:

Enter the address you want to use for sign in, email notifications, and password reset. You may need to verify this email before you can use Mattemost.


email address
Enter the address that you want to use for signing in, receiving notifications, resetting passwords, and receiving your account confirmation email.
user name

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

user name > Username

This comment has been minimized.

Copy link
@JeffSchering

JeffSchering Dec 6, 2016

Author Contributor

Agreed

2. If you don't have a direct link:

a) Navigate to the Mattermost sign-in page. You can get the address of the sign-in page from your administrator.
b) Click **Create one now**. The account creation page opens.

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Maybe mention that if the "Create one now" doesn't appear then an invite link is necessary to join the server.

6. Click **Next** to page through the tutorial.
7. On the last page of the tutorial, click **Next**. The all-members channel opens. By default, the all-members channel is called *Town Square*, but your administrator might have renamed it.

What to do next

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Propose this section is titled "Updating your Profile" and directly includes the contents of the updating-your-profile.rst doc

Updating your profile
=====================

Your profile includes information such as your name as it appears in Mattermost, your email address for receiving notifications and password resets, and your profile picture.

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Propose instead we mention what we recommend updating after account creation. In my mind that is adding a Name and profile picture.

Your profile includes information such as your name as it appears in Mattermost, your email address for receiving notifications and password resets, and your profile picture. >

After account creation it is recommended that you update your **Full Name** and **Profile Picture** to make it easier for your teammates to find you. Update your profile by clicking your username at the top left of the screen to open the Main Menu, then click **Account Settings**.

To learn more about **Account Settings** and configuring your profile please see the following related links:

- :doc:`../settings/account-settings`
- :doc:`../settings/configuring-notifications`
- Email
- Profile Picture

To update your profile

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Propose replacing this section. See the comment above ^

password
Enter a password that is at least 5 characters long. Your administrator might configure more restrictive requirements, such as the use of numbers, upper and lower case, and special characters. If the password that you enter does not meet one or more of the minimum requirements, you see a message that tells you what they are. You can then modify your password to meet the requirements.

To create an account

This comment has been minimized.

Copy link
@esethna

esethna Dec 6, 2016

Member

Propose this section just becomes the intro to the doc rather than its own section? Seems out of order with the workflow of how a person would sign up.

This comment has been minimized.

Copy link
@JeffSchering

JeffSchering Dec 6, 2016

Author Contributor

Yes, for the monolithic style of doc, this would be the case.

@esethna

This comment has been minimized.

Copy link
Member

esethna commented Dec 7, 2016

@JeffSchering thanks for the replies, did you want to work on addressing the feedback above or would you like me to submit a PR against your branch?

@JeffSchering

This comment has been minimized.

Copy link
Contributor Author

JeffSchering commented Dec 8, 2016

@esethna Thanks for taking a look at this... I'll start working on addressing your feedback and update the commits.

@JeffSchering

This comment has been minimized.

Copy link
Contributor Author

JeffSchering commented Jan 30, 2017

This was originally intended to be the start of re-doing the Getting Started section, but it's looking like it might take longer than expected, so I'm adding the WIP label again.

@lindy65 lindy65 changed the title First time user docs WIP: First time user docs Jan 31, 2017
@JeffSchering

This comment has been minimized.

Copy link
Contributor Author

JeffSchering commented Mar 15, 2017

Closing as this will be part of an upcoming project.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.