Discuss the Standardisation of Lesson Content Format

Following from this PR (#39606 ): There are many inconsistencies (nothing more than markup), which I would like clarification on, before continuing.

There is this section in the docs:

• Language keywords go in <code> tags. For example, HTML tag names or CSS property names
• The first instance of a keyword when it’s being defined, or general keywords (i.e. “object” or “immutable”) go in <dfn> tags
• References to code parts (i.e. function, method or variable names) should be wrapped in <code> tags.

I would like to expand on this with what would be best (look the nicest) for:

• Mentioning routes and non-code keywords like ‘POST’: (This form is set up to POST on /register…)

• Mentioning packages (in the typeface used by the brand, or always that of the package name) (Add BCrypt as a dependency…) OR (Add bcrypt as a dependency…)

• Should MarkDown always be used, when possible? (this list appears to change font with the HTML)

• Can we add something like:

Notes are placed at the end of a lesson’s content, and the word ‘Note’ is emboldend

---

Whilst this issue came about because of the mentioned PR, I would hope any conclusion could be added to the docs.

Here is a particular paragraph I am struggling with:

The logic of step 1, registering the new user, should be as follows: Query database with a findOne command > if user is returned then it exists and redirect back to home OR if user is undefined and no error occurs then ‘insertOne’ into the database with the username and password, and, as long as no errors occur, call next to go to step 2, authenticating the new user, which we’ve already written the logic for in our POST /login route.

1. Should the above be completely restructured into a proper list?
2. Should (findOne, insertOne, undefined, POST, and /login) all be contained with code tags (I dislike this, because of the current styling on the code tags; it makes the paragraph look patchy

[naomi-lgbt]

I’ll chime in with some thoughts:

Mentioning routes and non-code keywords like ‘POST’: (This form is set up to POST on /register…)

I think these should go in <code> tags as well. /register, for example, could technically be considered a “code part”.

Mentioning packages (in the typeface used by the brand, or always that of the package name) (Add BCrypt as a dependency…) OR (Add bcrypt as a dependency…)

This one I lean more toward using the package name, for clarity’s sake. And wrapping the package name in <code> as well.

Should MarkDown always be used, when possible? (this list appears to change font with the HTML)

I think so. Though if we transition to MDX I’m not sure.

Should (findOne, insertOne, undefined, POST, and /login) all be contained with code tags (I dislike this, because of the current styling on the code tags; it makes the paragraph look patchy

findOne and insertOne should definitely be in code tags, right? Those are methods…

(I dislike this, because of the current styling on the code tags; it makes the paragraph look patchy)

I think that paragraph as a whole is a bit messy. Rewording it could alleviate the patchy concern.

[RandellDawson]

I am not a fan of using em tags for anything here.