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

docs: minor fixes to how to work on coding challenges #48644

Closed
wants to merge 2 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
21 changes: 11 additions & 10 deletions docs/how-to-work-on-coding-challenges.md
Expand Up @@ -2,7 +2,7 @@

Our goal is to develop a fun and clear interactive learning experience.

Designing interactive coding challenges is difficult. It would be much easier to write a lengthy explanation or to create a video tutorial. But for our core curriculum, we're sticking with what works best for most people - a fully interactive, video game-like experience.
Designing interactive coding challenges is difficult. It would be much easier to write a lengthy explanation or to create a video tutorial. But for our core curriculum, we're sticking with what works best for most people -- a fully interactive, video game-like experience.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a style guide for this sort of thing? Using -- in a block of text is a bit unusual in my experience


We want campers to achieve a flow state. We want them to build momentum and blast through our curriculum with as few snags as possible. We want them to go into the projects with confidence and gain a wide exposure to programming concepts.

Expand All @@ -20,7 +20,7 @@ You can find all of freeCodeCamp.org's curricular content in the [`/curriculum/c

## Set up the tooling for the curriculum

Before you work on the curriculum, you would need to set up some tooling to help you test your changes. You can use any option from the below:
Before you work on the curriculum, you would need to set up an environment to help you test your changes. You can use any option from the below:

- You can [set up freeCodeCamp locally](how-to-setup-freecodecamp-locally.md). This is **highly recommended** for regular/repeat contributions. This setup allows you to work and test your changes.
- Use Gitpod, a free online dev environment. Clicking the button below will start a ready-to-code dev environment for freeCodeCamp in your browser. It only takes a few minutes.
Expand Down Expand Up @@ -61,7 +61,7 @@ Challenge instruction text, in markdown
Tests to run against user code, in pairs of markdown text and code block test code.

```js
Code for test one
Code for test number one
```

If you want dynamic output based on the user's code, --fcc-expected-- and --fcc-actual-- will be replaced with the expected and actual values of the test's assertion. Take care if you have multiple assertions since the first failing assertion will determine the values of --fcc-expected-- and --fcc-actual--.
Expand Down Expand Up @@ -118,7 +118,7 @@ console.log('freeCodeCamp is awesome!');

# --solutions--

Solutions are used for the CI tests to ensure that changes to the hints will still pass as intended
Solutions are used for the CI tests to ensure that changes to the hints will still pass as intended.

```js
// first solution - the language(s) should match the seed.
Expand Down Expand Up @@ -158,7 +158,8 @@ More answers

## --video-solution--

The number for the correct answer goes here.
The number for the correct answer goes here, with an 'url of video explanation'.

````

> [!NOTE]
Expand Down Expand Up @@ -197,7 +198,7 @@ Once you have your id, put it into the markdown file as the `id` field at the to
```yml
---
id: 5a474d78df58bafeb3535d34
title: Challenge Title
title: Title of the Coding Challenge
```

## Naming challenges
Expand All @@ -218,9 +219,9 @@ Here are some example challenge names:

Sentences should be clear and concise with minimal jargon. If used, jargon should be immediately defined in plain English.

Keep paragraphs short (around 1-4 sentences). People are more likely to read several short paragraphs than a wall of text.
Keep paragraphs short (around 1-4 sentences per paragraph). People are more likely to read several short paragraphs than a wall of text.

Challenge text should use the second person ("you") to help to give it a conversational tone. This way the text and instructions seem to speak directly to the camper working through the challenge. Try to avoid using the first person ("I", "we", "let's", and "us").
Challenge text should use the second person ("you") to give the text a conversational tone. This way the text and instructions seem to speak directly to the camper working through the challenge. Try to avoid using the first person ("I", "we", "let's", and "us").

Don't use outbound links. These interrupt the flow. Campers should never have to google anything during these challenges. If there are resources you think campers would benefit from, add them to the challenge's Guide-related article.

Expand Down Expand Up @@ -251,7 +252,7 @@ We track how long it takes for campers to solve challenges and use this informat

Each challenge should teach exactly one concept, and that concept should be apparent from the challenge's name.

We can reinforce previously covered concepts through repetition and variations - for example, introducing h1 elements in one challenge, then h3 elements a few challenges later.
We can reinforce previously covered concepts through repetition and variations, for example, introducing h1 elements in one challenge, then h3 elements a few challenges later.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would split this sentence up. I don't think that putting a comma here is correct grammar. As a general rule, commas should be used sparingly. They aren't replacements for conjunctions.

We can reinforce previously covered concepts through repetition and variation. For example, we can introduce h1 elements in one challenge and h3 elements a few challenges later.


Our goal is to have thousands of 2-minute challenges. These can flow together and reiterate previously-covered concepts.

Expand Down Expand Up @@ -373,7 +374,7 @@ There are separate comment dictionaries for each language. The [English version
Some comments may contain a word/phrase that should not be translated. For example, variable names or proper library names like "React" should not be translated. See the comment below as an example. The word `myGlobal` should not be translated.

```text
Declare the myGlobal variable below this line
Declare the myGlobal variable below this line.
```

> [!NOTE]
Expand Down