Freecodecamp: Equivocation logical fallacy in how the word "key" is used.

[Carradee]

For an example, see Challenge Record Collection.

You first describe a primary key for a particular collection of album data but and call it "its key"—which linguistically applies that key to the item and all its children.

Then you call something else a key altogether, without making the transition to refer to to the key for a specific child. That's equivocating on what you've already defined as "key" in context.

The vagueness and dropped transitions are linguistically sloppy and sabotage your stated target audience of newbies. As things stand, a person has to already know/understand at least some of the jargon and concepts in order to even understand what some of your lessons are trying to convey—and even then, what you're even asking for isn't always clear unless someone already knows what you're looking for, because you could mean multiple things.

For the record, this is not an uncommon problem, when experts are building something for beginners. Identifying and fixing this sort of linguistic issue = part of my day job.

[BKinahan]

I'm not sure you realize the irony of using linguistics jargon in your issue write-up, but as someone who spends time helping 'newbies' with the JavaScript challenges I can confidently say that people understand what 'key' refers to in each instance from the context of the instructions and the challenge code.

The majority of misunderstandings about this challenge relate to how to logically structure if statements or how to properly use dot or bracket notation to access property values (but not in a way that suggests referring to a property name as a key is confusing), and a few others crop up due to user typos. I'd imagine only linguists get caught up on whether the semantics are executed perfectly, so this seems to me like a case of bike shedding :)

With all that said, if you'd like to propose a specific language change that can make the instructions even easier to understand (in the Record Collection challenge or in others), I am certain that would be welcome suggestion :)

[Carradee]

I'm not sure you realize the irony of using linguistics jargon in your issue write-up,

Yes, I did that on purpose to illustrate my point. (Also notice that my target audience ≠ newbies.)

The majority of misunderstandings about this challenge

I was explicitly referring to an overall issue _of which that particular item was an example_. I referenced that one because it was explicit and self-contained there.

The overall issue would mean that folks who are getting confused by it are probably giving up before they hit that point in Free Code Camp—and they most likely can't verbalize why they're confused.

People who get confused by word usage or misuse usually can't explicitly identify what confused them. Manipulators and other forms of abusive persons actually take advantage of that in everyday life. That's about half of how and why they get away with so much. (The other half: People tend to hear/see and remember what they assume others "must've" meant.)

if you'd like to propose a specific language change

Definition of jargon when introduced (at least have a link to the particular definition being used) and specificity for words with multiple possible meanings would be helpful (and is, frankly, just good practice in technical writing).

For example, the lessons refer to "keys" well before ever defining that they're meaning "primary keys" in the sense of database jargon. For all the reader knows, the lessons could be meaning "a thing that provides a means of achieving or understanding something" (ref. Oxford). The only way to understand it as a primary key is to already have familiarity with primary keys and database logic.

As for that particular lesson, here's the text with notes in brackets.

_You are given_ [note that "given" is jargon in context—and logically, why would you be "given" (someone handing to you) an incomplete record of _your own_ record collection? the entire scenario's suspect _and you ignore that_, which doesn't help the goal of training folks in critical thinking] _an object_ [this should be linked to a definition] _representing_ [note that this use of "represent" is jargon; requires someone already understand the jargon use of "object"]  _(a small part of) your record collection_ [the "(collection)" variable is never actually defined, linguistically]. _Each album is identified by a unique id number_ [add "(its primary key)" to introduce that jargon term — and link that addition to the definition of "primary key"] _and has several properties_ [link this to the definition]. _Not all albums have complete information._

_Write a function which takes an id, a property (prop), and a value_ [for…any album in the collection, I assume, but that's not actually stated. Could be for one of the properties. Note that "a" and "an" explicitly indicate that the specific item is irrelevant.]

_For the given id_ [which given ID? The definite article "the" explicitly means you're referring to ONE specific item that has already been defined in context, but previous paragraph only refers to unspecific indefinite ones. Note that how you phrase this conflicts with how you reference prop below, so you might want to rephrase this to be consistent with that rather than that to be consistent with this] _in collection_ [note that "collection" has not been defined or described]:

_If_ [in context, "a" is needed—note that you used an article ("the") with "id" above] _prop does not contain the key_ [transition needed before this, somewhere in the lessons though not necessarily in this one, to specify that each array has a primary key that applies to its level] _"tracks", then update or set the value for that incomplete prop_ [this usage is again consistent with previous paragraph and inconsistent with opening of this one].

_If_ [see first comment on previous paragraph] _prop does not contain the key "tracks" before you update it, create an empty array before pushing_ [note: this is jargon, in context] _a track to it._

_If_ [see first comment on two paragraphs up] _prop does contain the key "tracks" and its_ [note: this sentence structure means that "its" is referring to "prop", not "tracks"] _value is non-blank, then push_ [note: this is jargon, in context] _the value onto the end of its existing tracks array._

_If value_ [notice that this is being inconsistent about syntax with these variables, again] _is blank, delete that prop._

_Always return_ [note: this is jargon, in context] _the entire collection object._

Not sure how the course is getting written, but I have noticed that—in general—some items are better and more clearly defined than others.

ETA: formatting adjustment

[Carradee]

Since the asked-for critique of the lesson's specific phrasing is confusing folks, I just tried another formatting method. The forum rather limits my options, though..

As another note, as written, the entire "If prop does not contain the key 'tracks'" etc. means that the user-created function should check and update or remove _only_ the property "tracks", which directly contradicts the validation requirements. Either that talking about the "tracks" property needs to have a transition indicating it's an example rather than explicit instruction, or the validation needs repair.

Between the misused grammar in the poor use of pronoun and articles + the omitted transitions in general, I have to assume the lesson lost a "for example" somewhere.

(This is not the first lesson wherein I've noticed that kind of disconnect between instructions and validation requirements, by the way, and I've double-checked with some professional programmers to verify it's not just me and that it is in fact explained badly.)

[raisedadead]

@Carradee Thanks a lot for the opinions and critique, and the in depth research you have done to state the point, the effort is much appreciated.

We are always open to suggestions, unfortunately the opening post and the subsequent ones are simply "TL;DRs" for most contributors to the project (and hence maybe be overlooked, no offence), hence I urge you to provide us with exact statement for the instructions that are "apt" for the challenge. This will help us make the change in the code base post inputs from the issue mods team.

Thanks again.

[Carradee]

TL;DR: The lessons on FreeCodeCamp not infrequently misuse English and contradict themselves between what the instructions ask for and what the validation checks.

That means there are multiple possible things that could've been intended, so it's impossible to give specific input on "This would work better for what was intended."

[raisedadead]

This does make sense, but as you should be aware the challenges are curated and developed and added to the code base by virtually hundreds of contributors, there are ought to be differences, so unless you can guide us with the changes to the "instructions" for this challenge I am afraid we would be not be able to incorporate the same, only to be critiqued by someone else.

So, I propose please give us the exact change that you wish to see, which can be debated on this thread and incorporated into this challenge.

As for the other challenges, should you please, raise separate issues and add the changes that you would wish to see, and they would be incorporated as well, post debate on their threads.

[Carradee]

The "so many contributors" is why I both pointed out the specific items and explained them, because these issues should already be in the style guide for the lessons. That's 101 of writing both tutorials and technical materials.

If FreeCodeCamp doesn't have a style guide or managing editors, that's a significant problem and it's making things far harder than they should be. (Both are things that should've been set up before the first lesson was released. That's basic planning for a project like this. Even Wikipedia has guidelines and managerial editors.)

Here's a potential solution with notes in bold (b/c items need linking) and variables formatted in italics. I had to make some assumptions about what was meant vs. what was actually written. I assumed the validator for the lesson trumps whatever was actually stated in the lesson.

[DELETE THE DUPLICATE PARAGRAPH]

The provided object [link "object" to the definition] (_collection_) represents (a small part of) your record collection. Each album is identified by a unique id number (its primary key [link "primary key" to the definition]) and has several properties [link "properties" to the definition]. Not all albums have complete information.

Write a function that takes an _id_, a property (_prop_), and a _value_.

For each _id_ given for _collection_:

If a _prop_ does not contain the key that's needed for a given _value_ (ex. a track entry, but the _id_ doesn't have the _prop_ _"tracks"_), then update or set the _value_ for that _prop_.

If a _prop_ does not contain the key (ex. _"tracks"_) for a given value, create an empty array for that key before setting it.

If a _prop_ contains a key with a non-blank value, then push the _value_ onto the end of its existing array (ex. add another track to _"tracks"_ after the tracks already on the list).

If a particular _value_ is blank, delete the associated _prop_.

Always return the entire _collection_ object.

The main potential problem here is that I don't think "for" logical structure has been taught yet, unless something's changed since I last looked at that. Logically, they should've been back with the if/else and the switches.

[raisedadead]

[DELETE THE DUPLICATE PARAGRAPH]

This has been resolved in #9319 and should reach the main website soon in the next release cycle.

Thanks @Carradee this looks pretty neat to me.
Opening up for inputs from others. /to @FreeCodeCamp/issue-moderators

Potential contributors, please wait and check for the open pull requests on the way related to this challenge.

[raisedadead]

@Carradee thanks for the feedback regarding style guide and editors.
Will take it up in the discussion and get back.

[manicmarvin]

For multi-author user-contributed collections of lessons/information a style-guide is essential. I have just moved from the _Basic Javascript_ section to the _Object Oriented and Functional Programming_ section, and I am struggling with the massive shift in the way each challenge/lesson is written/constructed. ( See #4177 )

I'm super appreciative of @Carradee's detailed (and unbelievably patient) explanation with the problems in FCC's _general_ inconsistencies in language (i.e the English language) and style and the ambiguities and confusion this causes. While I understand that Github issues primarily focus on solving exact and specific problems, I don't think @raisedadead's repeated insistence that this is an issue that @Carradee could help fix by writing out the text for the challenge over again is all that's needed. It's a much larger problem, that I feel needs priority.

It's surprising that FCC has not already paid attention to the need for a Style Guide and specifications for the ways in which lessons/challenges need to be constructed.

[raisedadead]

@manicmarvin : Yes, you are absolutely correct, a style guide is a high priority right now.

But unfortunately GitHub issues are not the media to discuss the same, hence my insistence for the specificity (apologies if that caused any confusion, we are always open to changes and ideas).

As I mentioned in my previous comment, the need for the style guide is being discussed in the Chat rooms, I have presented this to the project maintainers, and we should be reverting back on something concrete ASAP.

Please feel free to drop in your inputs in the Curriculum Development Chat Room.

Thanks once again and we appreciate all the thoughts, and feedbacks.

[QuincyLarson]

@Carradee @manicmarvin @raisedadead Thanks for broaching the discussion of a style guide.

Our current approach is to trust that contributors will write clearly, and that if they don't, another contributor will fix it. While this may sometimes cause an uneven experience for campers, it minimizes the barriers to contribution, which is vitally important.

It's interesting that Wikipedia came up. Here's their style guide - er, guides: https://en.wikipedia.org/wiki/Help:Introduction_to_the_Manual_of_Style/4

I don't know about you, but when I see a guide like that, any desire I have to contribute to Wikipedia melts away.

And it's not just me. Wikipedia is declining because of its "crushing bureaucracy": https://www.technologyreview.com/s/520446/the-decline-of-wikipedia/

Whenever organizations attempt to introduce new standards - however well intended - this is generally how it goes:

In my opinion, we should be getting rid of existing rules, not creating more of them. We've simplified our code of conduct over time, and I suspect its efficacy has only increased as a result.

[Carradee]

You're conflating. Style guides give _guidelines_ for the broad items and some specific details that can vary depending on source, not strict rules that cover every scenario.

So your comic is about something entirely different than what's under discussion. Perhaps that misunderstanding of what a style guide is = the problem.

Some specificity is needed for clarity, coherency, and consistency. Some details would be more the purview of editing rather than writing (ex. spaces or no spaces around em dashes?). Others are needed to cue the writers in about what experts don't naturally think about when writing tutorials.

There is a reason why people tend to specialize in either teaching or performing a task. Those are two distinct skills. And writing clearly is another distinct skill, as I illustrated in that word misuse I pointed out.

Wikiepedia used to use a style guide rather than a manual, but that in itself isn't really their problem—some folks are attracted to that list of specific instructions. The bigger problem is that they're expecting the volunteer writers to also be editors and formatters and quality control, when those are distinctly different jobs/tasks.

The best style guides ones give the basic foundation for what's expected, then refer to other sub-guides for more specific items _for those people who need that specificity_. But even designing a style guide like that requires identifying the patterns behind what's desired to be written or outright being produced.

You're expecting writing by the common to develop good technical writing—even though good technical writing is not a common skill at all. With reason. Good technical writing requires someone to be able to comprehend advanced topics without losing sight of the foundation where beginners start from, and to translate them clearly, with good writing skills.

Experts talk shop with other experts just fine. But how many can explain things in a way that the beginner understands, or even remembers having been a beginner? Free Code Camp claims to want to teach beginners, but they're being written in such a way that they essentially require a person to already have some familiarity with the underlying logic and jargon, to be able to understand what's being said—which is an environment that produces students who misapply things because they had to fill in their own definitions and they didn't get them correct.

This happens in every field. As an English class example, perhaps you've heard that the commas in a list mean "and", so the comma before an "and" is redundant. That's outright wrong. The comma gets omitted for space reasons from journalistic style, and regular US style is to leave it in _for parallelism_. Including the comma also is less prone to some potential clarity issues, when writing lists. But some folks didn't know that background, so that explanation of the "commas mean 'and'!" seems logical for that situation and got popular even though it's directly contrary to just about every other use of the comma, which then tends to sabotage folks' understanding of what a comma is and does.

So, now that I've pointed out that you've confused two different things, do you take issue with style guides or style manuals or both?

[manicmarvin]

While I agree with much of what @Carradee has pointed out (I've quoted the points I think are most pertinent), I do hope others reading this do not feel as antagonised by her comment.

I fear that @QuincyLarson is quite certain that a style-guide will be more detrimental to FCC's FOSS culture than helpful. Nonetheless I hope that others will join the conversation. While teh curriculum change will attempt to address many of the knowledge gaps that teh current curriculum produces, it does not address the need for consistency and, more importantly, the need for lesson writers/editors to more carefully consider the needs and prior knowledge of learners. In fact, the more expansive curriculum will likely magnify the existing problem as more contributors step into the foray.

Style guides give guidelines for the broad items and some specific details that can vary depending on source, not _strict rules_ that cover every scenario.

[...]

Some specificity is needed for clarity, coherency, and consistency. [...] Others are needed to cue the writers in about what experts don't naturally think about when writing tutorials.

[...]

Wikipedia used to use a style guide rather than a manual, but that in itself isn't really their problem—some folks are attracted to that list of specific instructions. The bigger problem is that they're expecting the volunteer writers to also be editors and formatters and quality control, when those are distinctly different jobs/tasks.

[...]

[...] designing a style guide like that requires identifying the patterns behind what's desired to be written or outright being produced.

Like I mentioned on Gitter,I think it's important that contributors understand that they are writing for the _Lowest Common Denominator_ and therefore have to explain or link to definitions of every piece of jargon/technical term they introduce, that they structure their lessons with an introduction to the concept, and example of how it plays out, an optional note on any exceptions or additional information and a concisely worded, unambiguous set of instructions for passing the waypoint.

The style guide, is less style in my mind and more structure. I imagine a guide that helps contributors question each of their assumptions about the prior knowledge of the learner as well as unstated assumptions within instructions.

I sincerely believe that there's a serious problem with some of the lessons precisely because there hasn't been a guideline to ensure consistency and clarity. This creates massive obstacles for people trying to learn to code who come from _very very varied backgrounds_ and do not necessarily have the same style/language as CS folk or other tech folk. In some cases, such as the _Objective Oriented Programming_ section, the massive change in structure from the previous section (_Basic Javascript_) is so unsettling that, I imagine, it scares some people away.

That said, I do understand that getting more contributions is key to ensuring the success and growth of FCC. One idea I have to mitigate the problem a strict style guide creates is a slightly different format for the style guide. One that's divided into two parts:

1. Section 1: A simplified, friendly stylistic primer that encourages contributors to question their own assumptions, and have a basic sense of how lessons should be structured and why they should more clearly defined and the need to elaborate on technical terms and concepts. Basically, well designed, pretty one-page website that's no more than 800 words, that simply encourages ways of thinking for contributors.
2. Section 2: A completely separate section -- a detailed and technical ^(by technical I mean re: grammar and style of human languages viz. English) manual that closely examines grammar, style, formatting, and structural conventions to create consistency at a more granular level. This need only be used by editors or moderators who can help ensure clarity and resolve ambiguities even they could not have written out the lesson itself, and not necessarily by the people who write the lessons! (People like me, learners from diff backgrounds -- like publishing, writing, etc, -- who can contribute by just editing the already created content and apply the existing style guide to maintain consistency.)

Nothing needs to be 'thrown back' at the lesson creator. Yes, they'll probably have to answer questions to provide clarity once in a while, but that's anyway something they'll likely need to do. What i'm suggesting is a set of guidelines, it literally a guideline available to be used by those who _want_ to. No rules, just another resource to help contributors who want it. A resource whose use is _encouraged_ by FCC, but never _demanded_

I believe this divides the work. It, in fact, opens the system to more contributions: those of people who could not write lessons, but can help change the language of them to be more accessible. I know someone will say that people like that (who want improve language) can do it anyway. But I can't. @carradee was able to identify precisely the problems with the lesson, probably because she _is_ an editor, writer, etc. I would have sensed a problem but could not pinpoint the specific improvements needed. A style guide would have helped me understand what was missing and find solutions.

To illustrate: Imagine a contributor, X, writes a lesson, it passes existing checks and is merged. Then Y and Z, learners or other contributors, notice its inconsistencies and use the detailed style guide to pinpoint the problems and rewrite. There's never any compulsion to follow more rules, but tools are provided so people know how to achieve that consistency.

I'm sure there are many other solutions that resolve both the problems of QA/consistency i.e. the learner's entry barrier and the problems of complicating the contribution process i.e. the contributor's entry barrier. I hope people will share them here. Enabling new learners to reach the higher levels, I feel, must be just as important as providing new materials for more advanced learners.

[Carradee]

The proposed multisection method of handling the style guide, divided into the various steps/skills, with related levels of technical detail, is the sort of thing I was thinking. And yes, it does enable more contributions, because it divides the lessons into modules / steps that can be handled by people according to their individual skills.

A lesson-making process could easily be :

1. Writer or Coder proposes specific lesson to teach.
2. Coder drafts exercises.
3. Writer drafts explanation.
4. Coder verifies that the written explanation actually matches the exercise.
5. Editor looks it over and asks any verifying questions.

Etc.

Yes, they'll probably have to answer questions to provide clarity once in a while, but that's anyway something they'll likely need to do.

Speaking as an editor, folks new to bridging their assumptions can have a lot of "throwbacks", from clarifying questions. Bridging assumptions takes practice.

There's never any compulsion to follow more rules, but tools are provided so people know how to achieve that consistency.

Bingo. :)