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

Repair most egregious mistakes in onboarding modal #1964

Merged
merged 3 commits into from Apr 20, 2017

Conversation

@yiskah
Copy link
Contributor

yiskah commented Apr 16, 2017

The changes made in #1883 broke the pedagogy and curriculum built into the design of the onboarding modals, which had been reviewed and approved by various other contributors. While the changed layouts of the pages make some of the original decisions impossible to re-implement without substantial work, these changes should at least make the modals not outright terrible.

The following fixes are in this PR:

The meaningless inaccurate confusing description of Mastodon was replaced with an actual basic explanation of federation. The language was modified to be friendly and conversational again. Grammatical errors were fixed. The explanations of local and federated timelines were re-ordered to be in the direct that the menus go, top to bottom, and the sentence was re-added which explains that they are what "public timelines" refers to (since this phrasing is used elsewhere in the UI) and suggests the user use them to discover who to follow. A figure of the profile picture that lives above the compose box was added to page two to serve as a landmark for less technically literate users to easily find the compose box and understand that the next page is moving upwards, so that they can find the search bar.

The remaining unrepaired mistakes that this PR do not fix is that the elephant drawing should be either removed or replaced with something less depressing; and room should be made to point users at the notifications column's settings icon because "how do I turn off the notification noise" is one of the most asked questions of new users and those icons are not easily noticeable. This last part may be made obsolete if the settings UI is later re-worked.

The deployed changes broke the pedagogy and curriculum built into the design of the onboarding modals, which had been reviewed and approved by various other contributors. While the changed layouts of the pages make some of the original decisions impossible to re-implement without substantial work, these changes should at least make the modals not outright terrible. 

The empty confusing description of Mastodon was replaced with an actual basic explanation of federation. The language was modified to be friendly and conversational again. Grammatical errors were fixed. The explanations of local and federated timelines were re-ordered to be in the direct that the menus go, top to bottom, and the sentence was re-added which explains that they are what "public timelines" refers to (since this phrasing is used elsewhere in the UI) and suggests the user use them to discover who to follow. A figure of the profile picture that lives above the compose box was padded to page two to serve as a landmark for less technically literate users to easily find the compose box and understand that the next page is moving upwards, so that they can find the search bar. 

Ideally, the elephant artwork should be either removed or replaced with something less depressing.  Room should be made to point users at the notifications column's settings icon because "how do I turn off the notification noise" is one of the most asked questions of new users and those icons are not easily noticeable. This last part may be made obsolete if the settings UI is later re-worked.
@@ -25,8 +25,8 @@ const PageOne = ({ acct, domain }) => (

<div>
<h1><FormattedMessage id='onboarding.page_one.welcome' defaultMessage='Welcome to Mastodon!' /></h1>
<p><FormattedMessage id='onboarding.page_one.federation' defaultMessage='Mastodon is a social network that belongs to everyone.' /></p>
<p><FormattedMessage id='onboarding.page_one.handle' defaultMessage='You are on {domain}, one of many independent Mastodon instances. Your full handle is {handle}' values={{ domain, handle: <strong>{acct}@{domain}</strong> }}/></p>
<p><FormattedMessage id='onboarding.page_one.federation' defaultMessage='Mastodon is a network of independent server instances joining up to make one larger social network.' /></p>

This comment has been minimized.

Copy link
@nightpool

nightpool Apr 17, 2017

Collaborator

"instances" is a weird, overly technical word here. would maybe just "independent servers" also work?

This comment has been minimized.

Copy link
@simonv3

simonv3 Apr 18, 2017

How about "independent servers (also known as instances)"

This comment has been minimized.

Copy link
@yiskah

yiskah Apr 19, 2017

Author Contributor

The word "instance" needs to be used since that is what is used everywhere else in the UX. And it needs to be used in a context where it is explained. Using parentheticals is typically not the best.

How about: "Independent servers linking up to form one larger social network. We call these servers: Mastodon Instances."

This comment has been minimized.

Copy link
@marrus-sh

marrus-sh Apr 19, 2017

Contributor

I think splitting this up into multiple sentences would be best. For example (just making this up on the fly) "Mastodon is a collection of servers which connect to form a larger network. Each server (known as an instance) is fully independent, blah blah federation."

Personally I feel like dropping all that terminology in a single sentence is a bit overwhelming, although I'm not clear on space requirements within the modal so maybe that's important.

This comment has been minimized.

Copy link
@yiskah

yiskah Apr 20, 2017

Author Contributor

I think using parentheses breaks up the sentence semantics, and makes it harder to process. I prefer to use independent clauses when explaining things. Also it's important to keep in mind that "Each server can talk to each other just the same" is already on the sign-up page.

@lutoma

This comment has been minimized.

Copy link

lutoma commented Apr 17, 2017

I prefer the way it is right now. I feel like most of these changes make the text too technical and difficult to understand for the average user, and add very little useful information.

I'm not very involved in the development and am not aware of the back story that lead to this, but I'm also very irritated by the PR message, stylizing it as though the text proposed here was the 'one true and correct' one, and calling the current version's wording 'mistakes', without actually making any good case as to why that is. It's also very unnecessarily agressive towards the current version («depressing», «outright terrible», «egregious mistakes») and not very conducive of a rational discourse. Just my $0.02.

@ericblade

This comment has been minimized.

Copy link
Contributor

ericblade commented Apr 17, 2017

I was more offended by the colors getting all completely out of whack when I started adjusting custom.scss, than I was by the text. Although I was also impressed that the colors actually changed in the onboarding after i changed custom.scss, but they no longer matched up at all with what I had in the UI.

@yiskah

This comment has been minimized.

Copy link
Contributor Author

yiskah commented Apr 19, 2017

If you want I can write up a document explaining why things are the way they are in depth. It's an orientation for new users. It's meant to teach them how to use and understand the site.

It's important to use words like "instance" because that is the official word that is used everywhere. If the word "instance" is too technical for new users it should not be used anywhere that a user will see. The purpose of using it here is to introduce the concept to a new user and teach them what it is. The moment a user starts using the site they will encounter the word "instance" everywhere they look. The purpose of this modal is not to convince a user to sign up for Mastodon it is to help them understand how to use it and what it is.

Regarding tone:
For about half of Mastodon's lifetime I was an unofficial community manager who welcomed pretty much every new user, individually, and helped them understand the site. The moment we hit Eternal September I began working on designs for this modal system to replace my individual efforts.

I have a degree in education through UX. I've done research on this. I have expertise. The design I drafted uses a curriculum and pedagogy based on my experience both in designing for learning and through having extensive experience interacting with new users and learning what concepts they struggle with, what explanations make sense for them, and what their common questions are.

I drafted a design, worked on it with others, got feedback at several stages including from Gargron and from end-users; and ultimately everyone agreed I should move forward with implementing the final design. I then spent about a week of free full time labor on top of my full time job (in the education sector) to implement my designs and when I merged it in we agreed we just had a couple things to polish before deploying it, trying to prioritize it before the media rush ended.

There is a reason my words regarding this should carry more weight than random men who are given more respect purely for being men, despite being new contributors if even contributors at all.

After getting feedback from others every step of the way, changes were made to my work without consulting me at all and references to the work I had already done was referred to as "bad" with no respect for the time, effort, thought, and energy which was put into this. Of course I was open to constructive criticism, I sought it out. Having my work taken and changed in ways which break the design, without consulting me, without giving me a chance to even be in the conversation given I didn't even know it was happening, and in said conversation insulting me repeatedly. That's disrespectful. That is hardly a good tone.

The changes that were made break the curriculum. The user is not introduced to the concept of federation in the version that went live, which was one of the most important components of the modal. Instead the phrase "Mastodon is a social network that belongs to everyone" is used. This phrase not only unhelpful to new users, it is blatantly false. Mastodon the network does not belong to everyone, it belongs to instance admins. Being an instance admin costs at minimum $5-10/month plus a lot of time and effort. That creates a class divide in who Mastodon the network belongs to. That's not necessarily a problem if you just avoid saying stuff like "Mastodon belongs to everyone." Does Mastodon the project belong to everyone? That's getting even more into strange complex technical concepts irrelevant to a new user.

The UI components are meant to be laid out to help teach the user how to visually scan the site to find these components later. In the new design, the UI components are abstracted and the user is given no guidance on where to find them. Some components are grouped together despite appearing in different forms from each other in the actial UI. On some screens, the words even wrap, causing the pseudo-buttons to be entirely different shapes from the actual UI.

Not to mention a lot of the replacement writing is stilted and unnatural in English. "Federated timeline lists posts" isn't something most people would say. It sounds grammatically incorrect.

The changes in this pull request are themselves compromises with the text in the deployed version. It is not the original phrasings, but tweaks to the new phrasings which reinstate the important concepts and words in order for the pedagogy of the modal designs to function.

If you absolutely must have things be more polite on my end, even though none of the men involved in this project have ever seemingly felt a need to be polite or respectful towards me (or my expertise, experience, or labor), then I can rename the title of this pull request to "Reinstate curricular pedagogy into onboarding modal design." I thought if I had used that then I would be the only one who even understood what the pull request was for. Since I'm apparently the only one who thinks about this stuff.

Simply put, if you have feedback on the designs and want to talk about how to modify them so they still serve their purpose, I am happy to have a conversation about it and I'm open to the idea that I can be wrong. But if you simply want me to be more polite, quiet, and respectful, then you need to offer me the same affordances.

I expect that even after this pull request there are many ways we can improve the onboarding experience either through changes to the modals or otherwise. At present, the versions of the modals that are live are confusing to new users and not properly explaining the basic things that they need to understand. The live versions jump into using phrases like "independent instances" with nothing to grab onto to understand that. They need to be fixed and this pull request does it.

I actually have the ability to just merge this myself if I wanted to. I'm being polite and sticking with the process of submitting it for review. Critique the design. Do not critique my tone. If you say "I am not involved in development and not aware of the context" then that is the sign that you are not properly informed and should simply abstain from telling a woman to be more polite.

@@ -90,26 +93,26 @@ const PageFour = ({ domain, intl }) => (
<div className='row'>
<div>
<div className='figure non-interactive'><ColumnHeader icon='home' type={intl.formatMessage(messages.home_title)} /></div>
<p><FormattedMessage id='onboarding.page_four.home' defaultMessage='Home timeline shows posts from people you follow'/></p>
<p><FormattedMessage id='onboarding.page_four.home' defaultMessage='The Home timeline shows posts from people you follow'/></p>

This comment has been minimized.

Copy link
@Gargron

Gargron Apr 19, 2017

Member

Do you insist on capitalizing the titles in-text?

This comment has been minimized.

Copy link
@yiskah

yiskah Apr 19, 2017

Author Contributor

It should be either "The Home timeline" or "The home timeline." Whichever is preferable to you. The word "The" needs to be there in English for it to sound natural. The T needs to be capitalized because it's the beginning of a new sentence. Everyone already says "the home timeline" "my home timeline" "the local timeline" etc. Sometimes they'll say "on public timeline" though? Not sure why that is. But because there are these different timelines, the word "Home" "Local" "Federated" come off as descriptors, not proper nouns.

If you really want to treat these as proper nouns akin to "Mastodon" versus "The Mastodon Network" then the sentence should be restructured. Written as "Home timeline shows" it doesn't come off as a proper noun. The word "Home" just looks like the regular word "home" at the beginning of a sentence. So when you read "Home timeline shows" it comes off as ungrammatical, like you forgot a word.

So if you're attached to it being proper nouns, then it should be something like "There are several different Timelines.

  • Home Timeline shows posts from people you follow.
  • Local Timeline shows public posts from everyone on your instance.
  • Federated Timeline shows public posts from everyone who is followed by someone on your instance."

By capitalizing "Timelines" in an earlier sentence, it frames them as proper nouns. It's also important that, if they are proper nouns, that it be "Home Timeline" and not "Home timeline." With "Home timeline" the word "Home" comes off as a proper noun, but not "timeline."

You don't say "Apple smartphone runs iOS" you say "Apple's smartphones..." or "The Apple smartphones..." (the latter sounds like an old person, but it's grammatically correct. It doesn't throw that P20 Spike in the brain of an English L1 speaker that says "This is wrong.") but if there's a proper noun called Apple Smartphone you capitalize both words. (e.g. Apple iPhone, "Apple" is a part of the name now, not a descriptor of "smartphone".)

I still think it sounds more natural not to treat them this way. "The Home timeline" or "The home timeline" feels right to me. Making "Timelines" into a proper noun feels to me like when corporations name their product "Fresh™" or "Joy™"

This comment has been minimized.

Copy link
@Gargron

Gargron Apr 19, 2017

Member

I only meant the H, i.e. "The Home timeline" vs "The home timeline"

This comment has been minimized.

Copy link
@yiskah

yiskah Apr 20, 2017

Author Contributor

In that case I can definitely make them lowercase.

@simonv3

This comment has been minimized.

Copy link

simonv3 commented Apr 19, 2017

Warning, not directly related to the PR: @yiskah I know you have said that you've spoken and helped onboard lots of people, I'm wondering if you have anything written up for that? I think it'd make a fantastic resource for http://opensourcedesign.net/ (I couldn't really find a better place to post this)

@yiskah

This comment has been minimized.

Copy link
Contributor Author

yiskah commented Apr 19, 2017

@simonv3 if you'd like! Get in touch with me somewhere else if you wanna talk about it. This isn't the right place for the discussion

@marrus-sh

This comment has been minimized.

Copy link
Contributor

marrus-sh commented Apr 19, 2017

On the contents of this PR:

These changes are small and they improve the readability/usability of the modal. I am critical of the sentiment (which I've heard often in Masto dev) that explaining to users how the software works is “too technical” and that it would be better if they were left uninformed. I think users have a right to know how their software operates and have a little more faith in their ability to pick up and retain new concepts.

Note that Mastodon does not currently have a Help Center or similar, so this modal is literally the only opportunity Mastodon presents them with for learning about the site. Given that, it is better to be thorough. If Mastodon gains better built-in help functionality in the future, that situation might change, but as-is I think these changes are needed.

Obviously it would be best if Mastodon had a style guide and a copy-editor to perfect the phrasing here and in other areas of this site, but that is beyond our capabilities at the moment and there's no reason not to push through a helpful change in the meantime.

Other things which I think would be useful:

I concur that information about notification settings would be useful; furthermore information about other user settings as well. Right now post privacy settings are mentioned but not explained, and it is not clear that you can change these defaults in user settings. My preference would be for users to be asked which default setting they would prefer in the modal (defaulting to Public or w/e if the modal is skipped), although I understand others have expressed concerns about asking users to fill out forms right away.

Noting that a lot of users are coming here from Twitter, it might be useful to include information (here or elsewhere) on things that are different between the two services; I get the feeling that a lot of users come in expecting features like dot-replies to be functional or not understanding how Search works. I understand Twitter has changed how it handles replies recently but the point remains.

Of course, this is getting to be a lot of content for an introductory modal, which suggests Masto needs a more formalized Help Center which users can consult. But that is a separate issue. (If a Help Center ever is implemented, the modal should point to it.)

Responding to other comments:

The purpose of a PR is to propose fixes to bugs or to add improvements where they were lacking. Acknowledging that there were problems with the previous implementation is a necessary part of this process. What is important is that these problems are well-identified and explained.

As my own 2¢, the purpose of a PR is not to have rational discourse about a problem (for which GitHub Issues more than suffice), but to propose a solution. I think this PR goes frankly above-and-beyond in identifying faults in the current implementation (although granted many of these were explained in a later comment) and furthermore makes a decent and non-damaging attempt at rectifying them. So, it should be merged.

</div>

<div>
<div className='figure non-interactive'><ColumnHeader icon='bell' type={intl.formatMessage(messages.notifications_title)} /></div>
<p><FormattedMessage id='onboarding.page_four.notifications' defaultMessage='Notifications show when someone interacts with you' /></p>
<p><FormattedMessage id='onboarding.page_four.notifications' defaultMessage='The Notifications column shows when someone interacts with you' /></p>

This comment has been minimized.

Copy link
@ashfurrow

ashfurrow Apr 20, 2017

Collaborator

While we're changing these, what do you think about adding periods to the end of this sentence, and to the end of the explanation for Home feeds as well? It would make it consistent with the rest of the copy text.

This comment has been minimized.

Copy link
@yiskah

yiskah Apr 20, 2017

Author Contributor

Yup. Will do. Those were removed from my original commit for some reason.

yiskah added 2 commits Apr 20, 2017
This commit addresses copy change suggestions made in the PR discussion

* Add periods to ends of sentences missing periods
* Made "Home" "Federated" "Local" and "Notifications" lowercase
* Separate explanation of "connecting" and the word "instance" into two sentences, to make the sentence less dense.
@yiskah

This comment has been minimized.

Copy link
Contributor Author

yiskah commented Apr 20, 2017

OK. Latest commit makes the following changes to address conversation in this thread:

  • Add periods to ends of sentences missing periods
  • Make "home" "local" "federate" and "notifications" all lowercase
  • Separate defining the word "instance" and the explanation of federation into two separate phrases to make the sentence less dense.
@yiskah

This comment has been minimized.

Copy link
Contributor Author

yiskah commented Apr 20, 2017

Also in terms of "Things to fix in a later pull" there's this post: https://slime.global/users/masklayer/updates/8782

The original pedagogy was based around making the UI elements easy to find once the modal closes.

@Gargron Gargron merged commit d251444 into master Apr 20, 2017
1 of 3 checks passed
1 of 3 checks passed
continuous-integration/travis-ci/pr The Travis CI build is in progress
Details
continuous-integration/travis-ci/push The Travis CI build is in progress
Details
codeclimate no new or fixed issues
Details
@Gargron Gargron deleted the yiskah-patch-1 branch Apr 20, 2017
aablinov added a commit to aablinov/mastodon that referenced this pull request Apr 20, 2017
* tootsuite/master: (72 commits)
  Repair most egregious mistakes in onboarding modal (tootsuite#1964)
  French translation cleanup (tootsuite#2223)
  Admin settings controller refactor, add specs, cleanup (tootsuite#2225)
  it may be mentions_status_id_index is duplicated of index_mentions_on_status_id index. (tootsuite#2224)
  Make Docker image buildable on ARM (tootsuite#2065)
  Fix PropTypes warning in OnboardingModal (tootsuite#2191)
  Use default locale for html lang in layouts (tootsuite#2212)
  Link to profile/feed/salmon from admin/accounts show page (tootsuite#2186)
  Removes timestamp from URLs. (tootsuite#2185)
  Fix tootsuite#2120 - Use Status#as_tag_timeline on public hashtag page (tootsuite#2182)
  Send nil for SMTP_LOGIN or SMTP_PASSWORD if it was left blank in the envfile, otherwise Ruby still attempts auth even if SMTP_AUTH_METHOD is none (tootsuite#2180)
  Add static gif for upload testing (tootsuite#2168)
  Fix tootsuite#2108 - Fix gif uploads (tootsuite#2171)
  Updated note about 'none' SMTP authentication method in .env.production.sample (tootsuite#2167)
  Add some Spanish translatoins (tootsuite#2170)
  Extract error messages to locale file (tootsuite#2162)
  Dutch language strings: a few important fixes (tootsuite#2163)
  Fixed hungarian translation (tootsuite#2158)
  Fix css for toot button when uploading images (tootsuite#2161)
  fix broken style when follower has long description (tootsuite#2159)
  ...
seefood added a commit to Toootim/mastodon that referenced this pull request Apr 28, 2017
* Repair most egregious mistakes

The deployed changes broke the pedagogy and curriculum built into the design of the onboarding modals, which had been reviewed and approved by various other contributors. While the changed layouts of the pages make some of the original decisions impossible to re-implement without substantial work, these changes should at least make the modals not outright terrible. 

The empty confusing description of Mastodon was replaced with an actual basic explanation of federation. The language was modified to be friendly and conversational again. Grammatical errors were fixed. The explanations of local and federated timelines were re-ordered to be in the direct that the menus go, top to bottom, and the sentence was re-added which explains that they are what "public timelines" refers to (since this phrasing is used elsewhere in the UI) and suggests the user use them to discover who to follow. A figure of the profile picture that lives above the compose box was padded to page two to serve as a landmark for less technically literate users to easily find the compose box and understand that the next page is moving upwards, so that they can find the search bar. 

Ideally, the elephant artwork should be either removed or replaced with something less depressing.  Room should be made to point users at the notifications column's settings icon because "how do I turn off the notification noise" is one of the most asked questions of new users and those icons are not easily noticeable. This last part may be made obsolete if the settings UI is later re-worked.

* Change copy

This commit addresses copy change suggestions made in the PR discussion

* Add periods to ends of sentences missing periods
* Made "Home" "Federated" "Local" and "Notifications" lowercase
* Separate explanation of "connecting" and the word "instance" into two sentences, to make the sentence less dense.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
9 participants
You can’t perform that action at this time.