Freecodecamp: Import challenge style guide into main repo

[erictleung]

Issue Description

The CurriculumExpansion repository has a challenge style guide and I feel that this should be imported into the main repository (this one) and maintained and updated from here.

This will probably help in standardizing the challenges and address some of the concerns brought up in this issue's thread https://github.com/freeCodeCamp/freeCodeCamp/issues/9291. Additionally, there have been questions (speaking from experience e.g. should I use <h4>Instructions</h4> or <hr>) when trying to remember or think about how something should be formatted. This is probably very valuable now when we've been formatting and prepping the new challenges for prime time.

cc/ @HKuz @QuincyLarson

[no-stack-dub-sack]

@erictleung Ha! All the work I've been doing on challenges lately, and frankly, I never even knew this existed.

I think this is super helpful, and I think it should be updated to include actual style guidelines like:

• language keywords go in <code> tags
• definitions, or general keywords (i.e. "object" or "immutable") go in <dfn> tags
• code examples go in <blockquote>s
• Instructions are delineated with <hr>s (newly decided)

And should also include tips like:

• What assertion libraries are OK to use (Node & Chai)
• User generated code can be accessed through the code variable

These are all things that I didn't know when I started contributing, that I had to just pick up along the way. If all this is included, I think it should be called just a "Challenge Writing Guide" and should be pointed to from somewhere in the main CONTRIBUTING.md file somewhere very obvious, so that new contributors don't have to struggle to figure out how to conform to our guidelines.

Although... I think this part of the guide is nuts based on our current map and feel it should be removed:

Each challenge should be solvable within 120 seconds by a native English speaker who has completed the challenges leading up to it.

Our current challenges in no way uphold this rule, and they wouldn't be any fun if they did. The algorithm sections in particular can take some folks hours or days to solve! Perhaps this should just be clarified based on section.

[HKuz]

Completely agree, thanks for bringing this up @erictleung! I have a page of chicken-scratched notes I used as guidance when looking over the challenges on the curriculum-expansion branch.

In addition to what @no-stack-dub-sack mentions, I also have:

• use short, clear sentences and keep paragraphs short (1-4 sentences), folks are less likely to read a wall of text
• use second person ("you") over first person plural ("we", "let's", "us") (see discussion)
• no emojis in challenges 😮 (they may have different cultural meanings around the world, or render differently on different systems)
• Notes in challenge text should use: <strong>Note</strong><br>Text of note... style
• Code examples and seed code uses indents with 2 spaces
• Based on this recent discussion, examples and seed code should use semicolons

This would definitely be helpful now since there are a number of contributors willing to help with pure formatting fixes in some sections.

I can certainly help with this, let me know 👍

[no-stack-dub-sack]

@erictleung @HKuz Awesome! I think by combining the material from the above 2 comments, we could have a super duper comprehensive guide that will be _incredibly_ helpful for newcomers!

This will be great, especially if we make sure to link to the newly created document in CONTRIBUTING.md!

[erictleung]

Within the ./seed/ directory might be a good place to place this guide. What do you all think?

code examples go in <blockquote>s

So I remember when we first started putting example code into block quotes. Initially, this was only for multi-line code examples. Just a single line of code used as an example would have been in <code> tags. Should we make it more uniform and have all code examples, not in inline paragraphs be in block quote tags?

[HKuz]

I like the blockquote style, but I generally found that single-line code examples were harder to read in them. If the example were wider than the blockquote box size, you'd have to scroll horizontally, and the scroll bar (while partially transparent) somewhat got in the way of reading the example. If we add some extra padding so the scroll bar shows up completely below the example text, it wouldn't be an issue.

[erictleung]

@HKuz agreed. There hasn't been an elegant way of viewing those wide, single lines of code.

[QuincyLarson]

@erictleung @HKuz are either of you interested in working on a PR that imports this style guide? Once it's in there, we can iterate on it over time.

[HKuz]

@QuincyLarson @erictleung - I can work on one this evening 😄