add contribution guidance to curriculum

CONTRIBUTING.md

@@ -36,86 +36,7 @@ We broadly use the [Teach Tech Together](https://teachtogether.tech/) pedagogica
 
 ## How to contribute
 
-### Propose a new narrative or activity
-
-We adopt _tested_ content into the main curriculum, so develop and try out your material first! Come to class, try it, and get feedback from the community. Come talk in #cyf-curriculum on Slack and iterate on your session.
-
-1. Develop your narrative or activity in a repo. If you're running a workshop, develop in https://github.com/CodeYourFuture/CYF-Workshops. If it's a project, make a separate repo for it.
-2. If you're recording a video, upload it to YouTube and make it public.
-3. Use your material and iterate on it with trainees.
-4. When you're ready to propose adoption, open a PR to this repo.
-5. The Curriculum team will consider your proposal and give you feedback.
-
-**We like to experiment.** If you have an idea, try it out and let us know how it goes! Keep your experiments small and test them early. (If you want to try something big, like a new module, come talk to us first.)
-
-Our curriculum threads a coherent line through all of this activity, so whatever worlds we explore, we can all come back here and find out _what_ to do _next_.
-
-_Most_ content we develop and use with classes will not be adopted into the core curriculum -- that's ok! We want to be free to experiment.
-
-## Bugs
-
-If you spot a bug, please let us know by [creating an issue](https://github.com/CodeYourFuture/curriculum/issues/new/choose) or opening a PR with the fix. Bug fixes are super welcome!
-
-As this front end composes many different repos, please open an issue in the repo where you found the bug. If you're not sure, open an issue in this [main repo](https://github.com/CodeYourFuture/curriculum/issues/new/choose).
-
-(If the content is pulled from another repo, there's a link next to the heading -- follow that link to the source repo and open an issue there.)
-
-## Developing the source website
-
-### To install
-
-You need the following software packages to run this curriculum:
-* `go`
-* `hugo` (must be the extended version) - please use version 0.136 extended, as more recent versions have a breaking change.
-* `npm`
-
-On macOS:
-
-```bash
-brew install go hugo npm
-```
-
-### To run locally
-
-#### Generate a token
-
-You'll need to get a fine-grained GitHub API token which allows read-only access to all public CYF repos from [this page](https://github.com/settings/tokens?type=beta).
-
-Click "Generate new token", enter a token name (can be anything), and how long you want the token to last (if you're doing a one-off contribution, pick a short value; if you're going to be a regular contributor, maybe a longer value).
-
-Make sure the Resource owner is _your_ account if you have a choice.
-
-The "Repository access" you need is "Public repositories (read-only)", and you don't need any account permissions:
-
-<details>
-<summary>Open to view screenshot of the required permissions</summary>
-
-![screenshot of required permissions](./readme_repository_access.png)
-
-</details>
-
-#### Set up `.env`
-
-Copy the `/curriculum/.env.example` to `/curriculum/.env`. Edit the file and then change the line that says `HUGO_CURRICULUM_GITHUB_BEARER_TOKEN` to contain the token that you have generated earlier.
-
-You can probably ignore the other entries.
-
-#### Run this command
-
-There are several websites in this repo - identify the one you want and make sure you're `cd`'d into that directory.
-
-Run this command in a terminal:
-
-```bash
-npm i
-npm run start:dev
-```
-
-If you find the build is very slow, and don't care about the issues being pulled into backlogs being precise, you can run:
-
-```bash
-npm run start:dev -- --environment issues-are-cached-and-incomplete
-```
+Contributions to the curriculum are always welcome. Help in navigating teh directory structure and instructions for local testing can be found in the [contribution guidelines pages](https://curriculum.codeyourfuture.io/guides/contributing/) of our curriculum.
 
 ### Site Search
 

org-cyf-guides/content/contributing/_index.md

@@ -9,17 +9,17 @@ menu: volunteers
 
 <!-- CYF-ONLY -->
 
-## 💯 Free and open
+## Free and open
 
 Code Your Future is a free training programme for refugees, asylum seekers, and other people excluded from education. All our classes are free and our teachers are volunteers. Since 2016, we have supported hundreds of people into great jobs in tech.
 
 We do our work in public. Our [free and open source curriculum](https://github.com/CodeYourFuture/curriculum) is collaboratively developed [on GitHub](https://github.com/CodeYourFuture/) by industry professionals around the world. We are a [registered charity](https://register-of-charities.charitycommission.gov.uk/charity-search/-/charity-details/5102561/what-who-how-where) in the UK and a [Digital Public Good](https://digitalpublicgoods.net/standard/).
 
 [Join our community](https://codeyourfuture.io/volunteers/). You are wanted and you are needed.<!-- END-CYF-ONLY -->
 
-## 🤝🏽 Making Contributions
+## Making Contributions
 
-Look for issues labeled "up-for-grabs" - these are low context and suitable for new contributors. To work on an issue:
+Look for issues labelled `up-for-grabs`, `help wanted` or `good first issue` - these are low context and suitable for new contributors. To work on an issue:
 
 - Comment on the issue to let others know you're working on it
 - Fork the repo and create a branch `feature/your-feature-name`
@@ -30,22 +30,22 @@ If you've spotted a problem, please check the existing issues and join the conve
 
 When making changes, focus on clarity and beginner-friendliness.
 
-## 🛟 Getting Help
+## Getting Help
 
 If you are an outside contributor, please join discussions and open tickets on our GitHub repos. If you can @mention a core contributor, that will help us see your message. (There are hundreds of active repos, so we don't always see everything.)
 
-If you have [joined our organisation](https://codeyourfuture.io/volunteers/), the **#cyf-syllabus-tech** channel is the best place to ask questions and get feedback.
+If you have [joined our organisation](https://codeyourfuture.io/volunteers/), the **#cyf-curriculum** Slack channel is the best place to ask questions and get feedback.
 
-You can also request a reviewers for your PR or pair program with an experienced contributor. We're happy to help new volunteers learn the codebase. There is an open code review Google Hangout once a week where you can ask questions and get feedback live. (Get the link in Slack.)
+You can also request reviewers for your PR or pair program with an experienced contributor. We're happy to help new volunteers learn the codebase. 
 
 Thanks for your interest! We're excited to work with you to provide life-changing education for all.
 
-## 🧑🏿‍💻 Joining the team
+## Joining the team
 
 Lots and lots of volunteers worldwide contribute to the curriculum. You don't have to join the Syllabus team to contribute, or even our our org.
 
 <!-- CYF-ONLY -->
 
-But if you'd like to meet us and get more involved, [join our organisation](https://codeyourfuture.io/volunteers/) as a volunteer. Once onboarded, introduce yourself in the #cyf-syllabus-tech channel on Slack. Let us know you'd like to attend a meeting and add your agenda points to the meeting link posted in that channel.
+But if you'd like to meet us and get more involved, [join our organisation](https://codeyourfuture.io/volunteers/) as a volunteer. Once onboarded, introduce yourself in the #cyf-curriculum channel on Slack. Let us know you'd like to attend a meeting and add your agenda points to the meeting link posted in that channel.
 
 The [Global Syllabus volunteer team](contributors) meets every two weeks online to talk strategy, take issues and plan the next sprint. We'd love to meet you!<!-- END-CYF-ONLY -->

org-cyf-guides/content/contributing/adding-updating/index.md

@@ -0,0 +1,153 @@
+---
+id: adding-updating-content
+title: Adding & Updating Content
+description: How to locate existing files and where to put new ones
+weight: 2
+---
+
+## Finding the Right Directory
+
+CYF's curriculum is designed to be modular. Each part of the course has its own sub-directory within the `curriculum` repo, and each module within those courses has its own GitHub repo with relevant code examples and exercises. We define the structure of the curriculum by specifying where each piece of content can be found, either as a path within `curriculum` or as a GitHub url.
+
+> [!NOTE]
+> We will use the Data Groups module of the Intro to Programming course as an example here but others follow a similar pattern.
+
+Within each course's directory there is a sub-directory for each module.
+
+```mermaid
+---
+title: org-cyf-itp structure
+---
+flowchart TD
+    itp@{ shape: docs, label: org-cyf-itp } --> onboarding@{ shape: docs, label: onboarding }
+    itp --> structuringData@{ shape: docs, label: structuring-data }
+    itp --> dataGroups@{ shape: docs, label: data-groups }
+    itp --> dataFlows@{ shape: docs, label: data-flows }
+```
+
+> [!NOTE]
+> There will be additional folders with other information required to edit the page, eg. details of the next stage of the course in the `piscine` folder
+
+Each module is broken into **sprints**. A sprint represents one week of work. The `success` folder contains the success criteria for a module.
+
+```mermaid
+---
+title: module structure
+---
+flowchart TD
+    itp@{ shape: docs, label: org-cyf-itp } --> dataGroups@{ shape: docs, label: data-groups }
+    dataGroups --> success@{ shape: docs, label: success }
+    dataGroups --> sprints@{ shape: docs, label: sprints }
+    sprints --> sprint1@{ shape: docs, label: "1" }
+    sprints --> sprint2@{ shape: docs, label: "2" }
+    sprints --> sprint3@{ shape: docs, label: "3" }
+```
+
+Each sprint is made up of **prep** (material to be read before class), **backlog** exercises (exercises to attempt before class), the **day plan** (the structure of the saturday class) and **success** criteria.
+
+```mermaid
+---
+title: sprint structure
+---
+flowchart TD
+    itp2@{ shape: docs, label: org-cyf-itp } --> dataGroups2@{ shape: docs, label: data-groups }
+    dataGroups2 --> sprints2@{ shape: docs, label: sprints }
+    sprints2 --> sprint1@{ shape: docs, label: "1" }
+    sprint1 --> prep@{shape: docs, label: prep}
+    sprint1 --> backlog@{shape: docs, label: backlog}
+    sprint1 --> plan@{shape: docs, label: day-plan}
+    sprint1 --> moduleSuccess@{shape: docs, label: success}
+```
+
+## Adding Prep Work
+
+The `prep` directory contains an `index.md` file listing all files to be included with a module. Each entry requires two pieces of information:
+
+- `name` specifies the page's title in the page map
+- `src` is the path to the file. This can either be a relative filepath from `curriculum/common-content/en` or a url to an external source, eg. GitHub. 
+
+Within `common-content` prep material is split across two directories:
+
+- `blocks` contains content which can be reused across different courses
+- `module` contains content specific to a particular module, subdivided by topic
+
+```mermaid
+---
+title: common-content structure
+---
+flowchart TD
+    common@{ shape: docs, label: common-content } --> en@{ shape: docs, label: en }
+    en --> blocks@{ shape: docs, label: blocks }
+    en --> module@{ shape: docs, label: module }
+```
+
+When adding new content:
+
+1. Create a new directory in the appropriate place. These can be nested within `blocks` or `modules`.
+2. In your directory create `index.md`
+3. Provide the appropriate front matter:
+
+```md
++++
+title = "Document Title"
+<!-- duration in minutes -->
+time = 120
+<!-- learning objectives as strings. -->
+objectives = [
+  "Learning objective 1",
+  "Learning objective 2",
+  "Learning objective 3",
+]
+<!-- build config - no need to edit this -->
+[build]
+  render = "never"
+  list = "local"
+  publishResources = false
++++
+```
+
+4. Write your content using markdown. Notes on styling and using render hooks can be found in the [Common documentation](https://common.codeyourfuture.io/).
+5. Add the path to your content to `index.md` in the `prep` directory.
+
+If your content is loaded from an external GitHub url you can skip steps 1 and 2.
+
+Changes made to prep content should appear immediately when the site is rebuilt locally. If they do not you likely need to clear a cached version of the site.
+
+### Code Examples
+
+If code examples are required for a task they can be stored in the module's repository. Every module has its own repo named `Module-<MODULE-NAME>`, eg. [Module-Data-Groups](https://github.com/CodeYourFuture/Module-Data-Groups). Add code to the appropriate sprint and include a link to it in your markdown.
+
+
+## Adding Backlog Items
+
+The backlogs for each sprint are generated by importing issues from GitHub. The [issues page](https://github.com/CodeYourFuture/Module-Data-Groups/issues) of each module's repo lists all exercises associated with the module with labels used to identify which sprint they belong to.
+
+To add a new backlog exercise, open a new issue and complete the template with the required information. Check out a [current backlog](https://itp.codeyourfuture.io/data-groups/sprints/1/backlog/) to see examples of what is required. 
+
+To remove an item from a backlog you can close the relevant issue.
+
+> [!CAUTION]
+> Other internal systems reference these issues - every issue **must** have labels for `sprint`, `submission` and `priority`.
+
+To prevent unnecessary calls to the GitHub API responses are cached. When testing locally the cache will need to be cleared in order to see changes made to GitHub issues.
+
+
+## Updating the Day Plan
+
+Similar to prep work, the `day-plan` directory contains an `index.md` file laying out the structure of the day. It covers two types of content:
+
+- Activities repeated across multiple classes (energisers, lunch breaks, etc.). These are stored in `common-content/en/blocks`.
+- Workshops for that class.
+
+Workshops can be defined in various places. Some are stored in `common-content/en/module` similar to prep content.
+
+Most workshops are stored in the [CYF-Workshops repository](https://github.com/CodeYourFuture/CYF-Workshops#:~:text=Welcome%20to%20CYF%20Workshops) and imported to `day-plan/index.md` using their url. There are some additional features available through this repository explained in its README. 
+
+Workshops may also be created in stand-alone repositories if needed. 
+
+
+## Updating Success Criteria
+
+At the sprint level, the [End of Sprint Review](https://itp.codeyourfuture.io/data-groups/sprints/1/success/) page lists all learning objectives defined in prep work and backlog exercises. This is generated at build time and does not need to be manually edited. If your learning objectives are not showing up here check they are formatted correctly.
+
+The [End of Module Review](https://itp.codeyourfuture.io/data-groups/success/) lists the criteria for passing the module. These criteria are referenced by other teams within the organisation - please **do not edit them** without prior discussion with a member of the core team.