Replace "First" and "Last" name code examples

[hergaiety]

In software it's common to jump to "First Name:" and "Last Name:" to demonstrate coding examples. However, such name patterns are a very Western culture practice and is not as international a concept as we may think.

...try to avoid using the labels ‘first name’ and ‘last name’ in non-localized forms...

W3C Personal names around the world

These concerns are not tied to language and may not be entirely solved by relying on guide translations. People with names that do not fit easily into the First and Last name boxes may be constantly risking entering form data in a way unexpected by some applications that could result in incorrect processing or entirely denying access to some individuals. Furthermore, as a transgender individual I risk being deadnamed and feel anxiety wondering whether a system is asking for my true name or the one legally recognized on a piece of plastic I have in my wallet.

These code examples may be merely examples, but teaching the right principals of programming at the start can pave the way for seeing the kind of applications we wish to see in the real world. I propose we follow the W3C's guide on Personal names by defaulting code examples to "Full name" in a single field.

---

• Configuration - Optional Features - default-async-observers
• Ember Data - Creating, Updating and Deleting - Updating Records
• Ember Data - Customizing Serializers - Attribute Names
• Testing - Testing Basics - Stubbing an Object
• Accessibility - Component Considerations - Accessible name - Adding a label to an input element
• Components - Helper Functions - Built-in Helpers - The let helper
• Components - Built-in Components - - Setting attributes on Input
• Components - Built-in Components - <Textarea />
• Models - Introduction - Models

---

• Configuration - Disabling Prototype Extensions - Functions
• Getting Started - Working with HTML, CSS, and JavaScript - JavaScript Classes
• Upgrading - Octane Upgrade Guide - Tracked Properties
• Application Concerns - Run Loop - Why is the run loop useful?
• In-Depth Topics - Autotracking In-Depth - Tracked Properties in Custom Classes
• In-Depth Topics - Native Classes In-Depth - Fields
• Upgrading - Glimmer Components - Arguments
• Upgrading - Native Classes

---

• Models - Defining Models - Defining Attributes Could be adjusted by making a computed property out of birthday to convert a string to a new Date() object.

[locks]

Thanks for bringing this up. This is something that has crossed my mind when working on documentation but that I never tackled in a more systematic way. I think the next steps here would be to do an evaluation of the current documentation (Guides and API docs) to see how and where "First Name/Last Name" examples are used, so that we can come up with the necessary approaches to address the problem.

Would you be willing to do the mentioned survey? You can ping me if you have any question regarding the examples, and then we can plan out the work from there!

[hergaiety]

@locks happy to do so!

• Accessibility - Component Considerations - Accessible name - Adding a label to an input element
• Components - Helper Functions - Built-in Helpers - The let helper
• Components - Built-in Components - - Setting attributes on Input
• Components - Built-in Components - <Textarea />
• Models - Defining Models - Defining Attributes
• Models - Introduction - Models
• Application Concerns - Run Loop - Why is the run loop useful?
• Testing - Test Types - Unit Tests
• In-Depth Topics - Autotracking In-Depth - Tracked Properties in Custom Classes
• In-Depth Topics - Native Classes In-Depth - Fields
• Upgrading - Glimmer Components - Arguments
• Upgrading - Native Classes

[ijlee2]

I don't think Testing - Test Types - Unit Tests has an example.

I ran git grep -in "firstname" to find 7 additional sections.

• Configuration - Disabling Prototype Extensions - Functions
• Configuration - Optional Features - default-async-observers
• Getting Started - Working with HTML, CSS, and JavaScript - JavaScript Classes
• Ember Data - Creating, Updating and Deleting - Updating Records
• Ember Data - Customizing Serializers - Attribute Names
• Testing - Testing Basics - Stubbing an Object
• Upgrading - Octane Upgrade Guide - Tracked Properties

[ijlee2]

I support the idea of using full name to illustrate a programming concept. However, I think we'll want to discuss feasibility and carefully plan how to update all sections, perhaps at a Learning Team meeting.

The sections that use only the first name or only the last name---these are easy to change. We can use full name or some other attribute instead.

The sections that use both first and last names (perhaps a section needed 2 tracked properties to illustrate an idea), I think we'll need to look at:

• Are there sections that are dependent of each other (i.e. a continuation)?
• Are there other easy-to-understand examples of 2 attributes that can be combined to arrive at another attribute?

@hergaiety Can you analyze for us further how the Guides currently use first and last names for each section?

[hergaiety]

Sure thing @ijlee2, it seems like to me we have two main categories.

Generic Data, "Could have picked any data attributes, really..."

These examples don't rely on the data necessarily being First & Last Names, but could have been any property at all. Many examples rely on a "person" model existing and thus we can use properties like: username, birthday, title, number, etc as needed. We should avoid examples of gender and address as both can become complicated as well.

• Configuration - Optional Features - default-async-observers
• Ember Data - Creating, Updating and Deleting - Updating Records
• Ember Data - Customizing Serializers - Attribute Names
• Testing - Testing Basics - Stubbing an Object
• Accessibility - Component Considerations - Accessible name - Adding a label to an input element
• Components - Helper Functions - Built-in Helpers - The let helper
• Components - Built-in Components - - Setting attributes on Input
• Components - Built-in Components - <Textarea />
• Models - Introduction - Models

Combining First & Last Name into a Full Name (demonstrating computed properties)

These are more difficult, Vue falls down here as well with the same examples. I believe it's easy to want to reach for the common example of concatenating ${firstName} ${lastName} but this is exactly what we want to avoid in this Issue.

Here are some alternative examples...

Switch to a String Reverse Example

String reversals are easy in JS, a common coding example in many coding texts, and is in no way a harmful example. Something like changing a computed property to listening for message property and outputting a this.message.split("").reverse().join("");. Vue demonstrates computed properties with the same example.

Much of the example code surrounding these examples currently use the person Ember Data Model, but could instead use post which we do in a few places to allow message to make contextual sense.

• Configuration - Disabling Prototype Extensions - Functions
• Getting Started - Working with HTML, CSS, and JavaScript - JavaScript Classes
• Upgrading - Octane Upgrade Guide - Tracked Properties
• Application Concerns - Run Loop - Why is the run loop useful?
• In-Depth Topics - Autotracking In-Depth - Tracked Properties in Custom Classes
• In-Depth Topics - Native Classes In-Depth - Fields
• Upgrading - Glimmer Components - Arguments
• Upgrading - Native Classes

Others...

• Models - Defining Models - Defining Attributes Could be adjusted by making a computed property out of birthday to convert a string to a new Date() object.

[chancancode]

Another possibility along the same vein and spirit is an (optional) title and a single name, concatenated? So we can have Dr. Tomster or something. Because it’s still talking about a person/user, I expect we would be able to retrofit that to the existing examples without having to refactor too much else.

[chancancode]

Making the title optional is realistic and also allow us to demonstrate slightly more complicated logic without having to teach/introduce string APIs like split and join (which is not hard to teach, but a bit off topic in most cases).

get formalName() {
  if (this.title) {
    return `${this.title} ${this.name}`;
  } else {
    return this.name;
  }
}

Another advantage of this is that it scales nicely. For examples that just needs a single field, you can omit title and just have a name.

[ijlee2]

Thanks, both @hergaiety and @chancancode, for providing additional information.

I think I prefer the example of,

get foobar() {
  if (this.foo) {
    return `${this.foo} ${this.bar}`;
  }
  return this.bar;
}

over the use of split.reverse.join.

title does make a good example for the pattern above, but I think I'd prefer to avoid deciding which name gets no title, Dr., Mr., Ms., Mrs., etc. I think it may be good if we can find examples for the pattern above that don't need to involve name. :) (I'll look for more examples tonight.)

I reserved time to discuss this GitHub issue as well as another at tomorrow's Learning Team meeting agenda. @hergaiety, would you be able to attend and help us figure out how to divide work, so that each PR can be of reasonable size for review?

[chancancode]

I think I'd prefer to avoid deciding which name gets no title, Dr., Mr., Ms., Mrs., etc. I think it may be good if we can find examples for the pattern above that don't need to involve name.

Hm. Why is that?

In the past, I have heard feedback (when mentoring/pairing) that some people find overly abstract, “academic”, foo bar style example difficult to follow or keep track of in their head. I personally don’t have that problem, but I can understand why.

The motivation of this seems to be to make the example more understandable and relatable for everyone, which I think is a good goal. I think it would be unfortunate if we end up losing that from making this change.

While not everyone has a preferred title (that’s why it should be optional), I think the idea of it is probably familiar enough for most people.

There are also plenty of gender-neutral honorary title that can be used as examples, such as Dr and Prof. Something like “Prof. Tomster” and “Dr Zoey” also feels thematically appropriate in a teaching context, and can be used consistently and repeatedly throughout the teaching materials. IIRC, there are examples of “scientists” (in getting started I think) that would fit well with this also.

I think it’s important to make sure we don’t accidentally exclude or alienate someone with a different culture/background where possible, I think the idea of a name that someone prefers to be addressed by is very universal and I don’t think there’s anything complicated and controversial that should cause as to want to avoid it. In this case it’s just about specific assumptions about what names look like that we need to be careful about (examples that validates names with /a-z/i are similarly problematic).

In the case of title, as long as it’s optional, I don’t think it’s particularly problematic. If anything, it’s an example of asking for and respecting someone’s preference. Not that we need to go out of our way to make a point about that in the teaching materials.

The fact that it will work with the existing examples without much adjustments to the surrounding text and flow is important, and this seems like a pretty good candidate that fits all the constraints IMO.

[ijlee2]

Ah, I think there was some misunderstanding due to lack of clarity in my explanation. I wasn't suggesting that we should use the names foo, bar, and foobar, but some example that fits the code pattern that you suggested.

For Tomster and Zoey, I think it's fine to address them as Professor or Doctor. I was initially concerned because our Guides currently have names of real people. I suppose we can change these names to Tomster or Zoey.

[hergaiety]

In the example of a person's Title, are we only focusing on the English interpretation and usage? https://www.w3.org/International/questions/qa-personal-names, https://en.wikipedia.org/wiki/Title, https://www.gordon.edu/styleguide/names-titles all introduce potential confusion around what an international system for titles and title concatenation may be (although I admit most of the time it's a prefix). Consider W3c's example of Herr Professor Doktor Schmidt

Many people are a Junior or Senior (Jr., Sr.) which I often see suffixed onto a name, which may be important in differentiating the parent from the child.

I also see many title form input solutions that rely on dropdowns to offer a limited number of options, some of which are gendered like "Mrs." or "Mr." although luckily those are going the way of the dodo (no longer really used).

That all being said, I'm digging deep into potential concerns that may not be a big deal. I only wish that we don't replace one problem with a slightly different one. Software docs are what encourage patterns for the kinds of apps we wish to see in the real world.

---

Alternatively...

Swift's Center of a Rectangle Calculation
https://docs.swift.org/swift-book/LanguageGuide/Properties.html

Similarly, we could do a simple width * length = area kind of computed property. Easy to understand to me, useful, and clearly demonstrates the intent. It doesn't fit in with a person model but the issue here may be that we're trying to shove a square peg into a round hole.

[ijlee2]

@hergaiety Apologies for a late reply. The Learning Team and I discussed how to make PRs today, and I can debrief you more later and help answer questions that you may have. Currently working on work stuff. :)

[chancancode]

@hergaiety You bring up some good points!

I could be wrong about this, but if I understand it correctly, I think the concerns are slightly different in nature.

The problem with first and last name (from my understanding of the article you linked) is that those words are tied to/implies an ordering, which only makes sense if you are used to writing down your name a certain way (the way that most English-speaking countries do – given name first, then family name last).

This is especially confusing for people coming from cultures that does have the same given/family name concept but write them in the opposite order. Growing up speaking Chinese first and English second (but learning both at the same time 😅), I am very familiar with this confusion personally and probably didn't fully internalized what first and last name meant until after I moved to North America and had to fill in a lot of English-only forms, both on the Web and IRL.

So, my understand is, the problem with first and last name, is first and foremost, the label itself and the implied/assumed ordering, which makes it foreign and not relatable to some readers.

Secondary to that, there are cultures that just doesn't have the concept of a given/family name at all, but that is relatively rare, and as per the article, "short of very localized customization, this is probably the best we can make a generic form". (Referring to labeling the fields as family/given names when you must have them separate.)

The take away is (at least how I understood it) that the most precise thing to do is the hyper-localize your products, but since you most likely won't have the resources to do that, if you data modeling doesn't require it, the easiest and most generic solution is to just ask for a single name. I think that is reasonable, and it's a good reason to avoid using that in our example.

Title is a bit different, in that it is fairly universal and relatable, at least when it's optional. It is true that some cultures uses it in different positions, but that is a localization issue, and given that the examples are given in English and demonstrating building a English-based product, personally I think that is acceptable and no more problematic than the input labels are in English and not localized.

It would be great if we localize the documentation into more languages. If and when we do that, we may have to tweak the examples (e.g. the ordering of the concatenation) in additional to the text. In theory it would be easier to find an example that doesn't have that particular problem, but that seems like a problem we can solve down the road since localizing the documentation is nowhere to be found on the roadmap, and this seems like a relatively small problem compared to the overall lift that would be required in that case.

Of course we can also iterate on this to find slightly more neutral/widely-applicable examples, such as using organization/job title, that kind of stuff, and I have no objection to that. In the meantime, it seems like going with name and title will resolve the biggest issues with first and last name and allow us to move away from that fairly quickly as it should be more-or-less of a drop-in replacement in existing examples.

In the long run, if we are do more work to refactor things, I don't have a particularly strong attachment to using "Person" as an example. I do think we are overdue for a pass to unify the examples for continuity sake and we can explore more options there.

However, generally speaking, I do think "Person" is highly relatable example for web developers. Given the motivation here is to avoid making unfamiliar/non-relatable references unnecessarily, if we do switch out the examples eventually, I do think we should need to hold that constraint just as strongly and avoid going in the abstract/academic examples direction that are commonly found in programming documentation (foo bar, shapes, vehicles, ...) and favor things that are more grounded in reality like people/users, posts (in a blog), products (in a shopping site), etc.

[hergaiety]

@chancancode you bring up some really great points, I feel a lot better about using title if that's the direction we want to go in.

[ijlee2]

I got to chat with @hergaiety on Discord to summarize the Learning Team meeting on July 30 and help answer questions. I'll do my best to summarize both the meeting and chat here: 🙂

• Everyone on the Learning Team was on board with @hergaiety's proposal to update the examples. The use of titles Dr. and Prof. with the names Tomster and Zoey was approved.

• I think we can look at using another example if it is appropriate for the surrounding text (refer to each section for context). A few practical examples may be,

  - aspectRatio = width / height (for an image)
  
  - a string of CSS classes (to show an if conditional)
  
  - canEdit = @user.isAdmin || @user.isManager (perhaps for a CMS)
  
  - emailAddress = username + domain
  

• It's up to @hergaiety how many versions to update and how many PRs to make. We (reviewers) will be accomodating. A few recommendations for making PRs were:

  - Start with `release` (3.20)
  
  - Make 1 type of change in a single PR or a single commit
  
  - Keep a checklist in this issue to stay motivated
    and help the team check in and lend help as needed
  

• In the meeting, the idea of also updating the examples in API Guides was brought up (this wasn't in the initial proposal). @hergaiety would like to work on updating the Ember Guides first.

[ijlee2]

This issue (updating the examples in release directory) has been completed thanks to @hergaiety!

I suggest that we backport the changes to 3.15 - 3.20 as a part of Hacktoberfest event.