Workshop Creation Documentation Gaps

[Jeevankumar-s]

While creating a workshop using pnpm run create-new-project, several CLI prompts and workflow steps are not clearly explained in the current documentation. This can cause confusion for contributors.

Affected Page : https://contribute.freecodecamp.org/how-to-work-on-workshops/

Below are the areas that need clarification:

1. Certification Selection Not Documented

   The CLI asks:

   Which certification does this belong to?

   The docs do not explain:

   • How to choose the correct certification (e.g., javascript-v9)

   • That this determines the superblock where the workshop appears

2. Help Category Selection Not Explained

   The CLI asks:

   Choose a help category

   The docs do not explain:

   • What the help category represents

   • How it relates to the certification

   • That it usually matches the certification subject (e.g., JavaScript → JavaScript)

3. Block Label Mapping Is Unclear

   The CLI asks:

   Choose a block label

   Docs mention blockType: workshop but ...

   • do not clearly state that this corresponds to selecting “workshop” in the CLI.

4. Chapter Selection Not Explained

   The CLI asks:

   What chapter should this project go in?

   The docs do not explain:

   • What a chapter represents

   • That it maps to folders like javascript

   • That *-certification-exam is reserved for exams

5. Module Selection Not Explained

   The CLI asks:

   What module should this project go in?

   The docs do not clarify:

   • What a module represents

   • How it maps to folders (e.g., javascript-objects)

   • How module placement affects workshop order

6. Position Within Module Not Explained

   The CLI asks:

   At which position does this appear in the module?

   The docs do not explain:

   • That this controls ordering

   • How contributors should determine the correct number

   • How to verify placement after creation

7. pnpm run clean:client Not Documented

   After project creation, the CLI instructs:

   pnpm run clean:client

   The docs do not mention:

   • This command

   • Why this is needed

   • When it should be run

   • Whether it is always required

8. pnpm run develop Not Documented

   To view the workshop in the full app (http://localhost:8000), contributors must manually run:
   
   pnpm run develop

   The docs do not explain:

   • That this is required to test in the full app

   • The difference between, Challenge Editor (port 3300) & the Full app (port 8000)

9. Step Creation Commands Are Confusing

   The Challenge Editor shows:

       pnpm create-next-challenge
       pnpm insert-challenge
       pnpm delete-challenge
   

   But the workshop docs describe:

       pnpm run create-next-step
       pnpm run create-empty-steps
       pnpm run insert-step
       pnpm run delete-step
       pnpm run update-step-titles
   

   This creates confusion because:

   • *-challenge and *-step terminology is not clearly explained

   • It’s unclear which scripts apply to workshops

   • The recommended workflow is not clearly defined

10. challengeType for Workshop Steps Not Documented

The workshop documentation does not clearly explain:

• Which challengeType value should be used for workshop steps
• What the relevant challengeType values represent

11. Updating intro.json When Replacing the Auto-Generated Intro Not Explained

The documentation does not clarify:

• That the intro content is stored in intro.json
• That contributors must update intro.json and placing the new block entry in the correct position relative to other blocks

[majestic-owl448]

That it maps to folders like javascript

chapters and modules are not folders, the only folders we have are for blocks
but they match the division of the curriculum at different levels

---

if you were to work on the docs update, what parts would you say you are not personally aware of now that you have worked for a while on contributing to the curriculum?

[Jeevankumar-s]

That it maps to folders like javascript

chapters and modules are not folders, the only folders we have are for blocks but they match the division of the curriculum at different levels

if you were to work on the docs update, what parts would you say you are not personally aware of now that you have worked for a while on contributing to the curriculum?

You’re right chapters and modules are structural divisions, not folders. I’ll update the issue wording.

My main point is that the overall hierarchy (certification → chapter → module → block → steps) isn’t clearly explained.

I’ll revise the issue accordingly.

[majestic-owl448]

if you were to work on the docs update, what parts would you say you could not write because you don't know the answers now that you have worked for a while on contributing to the curriculum?

[Jeevankumar-s]

if you were to work on the docs update, what parts would you say you could not write because you don't know the answers now that you have worked for a while on contributing to the curriculum?

As requested by @hbar1st , I’ve documented the areas where I experienced confusion during the workshop creation process. These are based on the parts I would currently hesitate to write documentation for confidently (e.g. module positioning, CLI step mapping, and local development workflow).

It also seems that parts of the current contributing guide may be outdated or not fully aligned with the current CLI workflow, which contributed to the confusion.

If any of these points are misunderstandings on my part, I’d really appreciate clarification so I can update the issue accordingly.

[majestic-owl448]

certification selection: it's assigned when the project is planned

---

help category: it determines in which forum subforum the automatically created post with template text will be assigned when using the help button

---

blockType is outdated, the name was changed to blockLabel, it determines the label on the block. It seems that this update was missed somewhere.

---

chapter and module should also be determined when the project is planned. Including where it goes inside the module. The order is the position of the block in the module, 1-indexed. The final position and the position to use can be different because the script only those the blocks that are currently existing, while there can be more that are planned but do not exist yet, like if you are adding the 6th block in a module, but right now the module containes only 2 blocks, you need to check where it goes relative to the two existing modules.

When you open a certification, for example javascript-v9, these are the chapters:

these are the modules:

and inside modules there are blocks

how blocks go in superblocks, chapters and modules is determined by the files curriculum/structure folder, the content of the blocks can be found in curriculum/challenges/english/blocks, while curriculum/challenges/english/certifications determines which are the requirements to get a certification.

---

pnpm run clean:client, I never use this, I usually use clean-and-develop, which still cleans the cache. clean cleans the cache, it can be needed depending on the changes when building locally to avoid seeing old things and make the new changes appear. @ojeytonwilliams can confirm for what things cleaning cache is recommended.

---

are you sure that develop is not documented? isn't it part of the instructions on how to set up freeCodeCamp locally? it even mention the port https://contribute.freecodecamp.org/how-to-setup-freecodecamp-locally/#step-4-start-the-client-app-and-api-server

and for the challenge editor it is mentioned here https://contribute.freecodecamp.org/how-to-work-on-workshops/#using-the-challenge-editor

---

Step Creation Commands

the challenge-editor may need updating, we do not use the *-challenge ones for steps

also because the *-challenge steps create files with a different naming convention (not the ID number)

but, about namings, challenge is generic, it's any file you can find inside a block

step is specifically for the challenges inside workshops (the *-step scripts are specifically for workshops)

[hbar1st]

In my opinion, the workshop page should include all the steps (even if that means ones that were mentioned elsewhere are repeated or linked to if they are more than one)

[Jeevankumar-s]

certification selection: it's assigned when the project is planned

help category: it determines in which forum subforum the automatically created post with template text will be assigned when using the help button

blockType is outdated, the name was changed to blockLabel, it determines the label on the block. It seems that this update was missed somewhere.

chapter and module should also be determined when the project is planned. Including where it goes inside the module. The order is the position of the block in the module, 1-indexed. The final position and the position to use can be different because the script only those the blocks that are currently existing, while there can be more that are planned but do not exist yet, like if you are adding the 6th block in a module, but right now the module containes only 2 blocks, you need to check where it goes relative to the two existing modules.

When you open a certification, for example javascript-v9, these are the chapters:

these are the modules: and inside modules there are blocks how blocks go in superblocks, chapters and modules is determined by the files `curriculum/structure` folder, the content of the blocks can be found in `curriculum/challenges/english/blocks`, while `curriculum/challenges/english/certifications` determines which are the requirements to get a certification.

pnpm run clean:client, I never use this, I usually use clean-and-develop, which still cleans the cache. clean cleans the cache, it can be needed depending on the changes when building locally to avoid seeing old things and make the new changes appear. @ojeytonwilliams can confirm for what things cleaning cache is recommended.

Thanks for clarifying about clean vs clean-and-develop.

Just to clarify my original point: the CLI explicitly instructs to run:

pnpm run clean:client

However, this exact command is not mentioned in the workshop documentation page.

are you sure that develop is not documented? isn't it part of the instructions on how to set up freeCodeCamp locally? it even mention the port https://contribute.freecodecamp.org/how-to-setup-freecodecamp-locally/#step-4-start-the-client-app-and-api-server

and for the challenge editor it is mentioned here https://contribute.freecodecamp.org/how-to-work-on-workshops/#using-the-challenge-editor

Thanks for pointing that out.

You’re correct that pnpm run develop is documented in the local setup guide. My concern is more about the workshop-specific workflow.

When using the Challenge Editor and clicking “View Live Version”, it opens http://localhost:8000. However, the workshop page does not clearly state that contributors must have pnpm run develop running in order for that link to work.

The only related instruction on the workshop page mentions:

pnpm challenge-editor-setup

but it does not explicitly clarify that:

• develop must be running for the full app (port 8000),
• the Challenge Editor runs separately (port 3300),
• and both may be needed depending on what the contributor is testing.

Step Creation Commands

the challenge-editor may need updating, we do not use the *-challenge ones for steps

also because the *-challenge steps create files with a different naming convention (not the ID number)

but, about namings, challenge is generic, it's any file you can find inside a block

step is specifically for the challenges inside workshops (the *-step scripts are specifically for workshops)

[Jeevankumar-s]

@majestic-owl448 Thanks for the clarification.

I now understand that:

Certification, chapter, and module placement are determined during the project planning stage.

Ordering is 1-indexed and based on the currently existing blocks in the module.

The overall hierarchy is defined in curriculum/structure, while block content lives in curriculum/challenges/english/blocks, and certification requirements are in curriculum/challenges/english/certifications.

blockType being renamed to blockLabel explains part of the earlier confusion in the docs.

I think adding a short clarification section in the workshop guide summarizing these structural concepts would make it much easier for new contributors to understand how workshops fit into the broader curriculum.

[majestic-owl448]

with this in mind we can start making some updates, starting from the straigthforward things, like updating blockType to the correct term

and then we can think of how to restructure the various things

is it mentioned that the last step (and only the last step) needs a --solution-- header with the final solution? the tests testing on the seed code of the next step (or the solution if last step)?

we can also think of updating the final message with the CLI tools, it has been reused as is in multiple ones
https://github.com/freeCodeCamp/freeCodeCamp/blob/7a7cccc8632c9c9235c8cb7222c37eef9a260903/tools/challenge-helper-scripts/create-language-block.ts#L607
https://github.com/freeCodeCamp/freeCodeCamp/blob/7a7cccc8632c9c9235c8cb7222c37eef9a260903/tools/challenge-helper-scripts/create-project.ts#L401

[Jeevankumar-s]

with this in mind we can start making some updates, starting from the straigthforward things, like updating blockType to the correct term

and then we can think of how to restructure the various things

is it mentioned that the last step (and only the last step) needs a --solution-- header with the final solution? the tests testing on the seed code of the next step (or the solution if last step)?

we can also think of updating the final message with the CLI tools, it has been reused as is in multiple ones https://github.com/freeCodeCamp/freeCodeCamp/blob/7a7cccc8632c9c9235c8cb7222c37eef9a260903/tools/challenge-helper-scripts/create-language-block.ts#L607 https://github.com/freeCodeCamp/freeCodeCamp/blob/7a7cccc8632c9c9235c8cb7222c37eef9a260903/tools/challenge-helper-scripts/create-project.ts#L401

Also, can we include clarification in the workshop docs about:

• The correct challengeType to use for workshop steps (and what the relevant types represent)?
• The requirement to update intro.json on replacing the auto-generated intro?

[majestic-owl448]

whatever needs to be added that makes the process more clear
the intros are in intro.json tho, not in <block-name>.json

the challengeType would be useful, I usually go by looking at other challenges of the same type

[Jeevankumar-s]

whatever needs to be added that makes the process more clear the intros are in intro.json tho, not in <block-name>.json

the challengeType would be useful, I usually go by looking at other challenges of the same type

done udpated 👍

[majestic-owl448]

--before-all--, --before-each--, --after-each-- and --after-all-- could also merit a mention, they are useful only sometimes, but when they are useful they are useful

[majestic-owl448]

if you feel up to it you could start a first PR correcting the outdated/misleading infos @Jeevankumar-s , then we can plan how to add everything else that is missing