|
| 1 | +--- |
| 2 | +id: adding-updating-content |
| 3 | +title: Adding & Updating Content |
| 4 | +description: How to locate existing files and where to put new ones |
| 5 | +weight: 2 |
| 6 | +--- |
| 7 | + |
| 8 | +## Finding the Right Directory |
| 9 | + |
| 10 | +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. |
| 11 | + |
| 12 | +> [!NOTE] |
| 13 | +> We will use the Data Groups module of the Intro to Programming course as an example here but others follow a similar pattern. |
| 14 | +
|
| 15 | +Within each course's directory there is a sub-directory for each module. |
| 16 | + |
| 17 | +```mermaid |
| 18 | +--- |
| 19 | +title: org-cyf-itp structure |
| 20 | +--- |
| 21 | +flowchart TD |
| 22 | + itp@{ shape: docs, label: org-cyf-itp } --> onboarding@{ shape: docs, label: onboarding } |
| 23 | + itp --> structuringData@{ shape: docs, label: structuring-data } |
| 24 | + itp --> dataGroups@{ shape: docs, label: data-groups } |
| 25 | + itp --> dataFlows@{ shape: docs, label: data-flows } |
| 26 | +``` |
| 27 | + |
| 28 | +> [!NOTE] |
| 29 | +> 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 |
| 30 | +
|
| 31 | +Each module is broken into **sprints**. A sprint represents one week of work. The `success` folder contains the success criteria for a module. |
| 32 | + |
| 33 | +```mermaid |
| 34 | +--- |
| 35 | +title: module structure |
| 36 | +--- |
| 37 | +flowchart TD |
| 38 | + itp@{ shape: docs, label: org-cyf-itp } --> dataGroups@{ shape: docs, label: data-groups } |
| 39 | + dataGroups --> success@{ shape: docs, label: success } |
| 40 | + dataGroups --> sprints@{ shape: docs, label: sprints } |
| 41 | + sprints --> sprint1@{ shape: docs, label: "1" } |
| 42 | + sprints --> sprint2@{ shape: docs, label: "2" } |
| 43 | + sprints --> sprint3@{ shape: docs, label: "3" } |
| 44 | +``` |
| 45 | + |
| 46 | +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. |
| 47 | + |
| 48 | +```mermaid |
| 49 | +--- |
| 50 | +title: sprint structure |
| 51 | +--- |
| 52 | +flowchart TD |
| 53 | + itp2@{ shape: docs, label: org-cyf-itp } --> dataGroups2@{ shape: docs, label: data-groups } |
| 54 | + dataGroups2 --> sprints2@{ shape: docs, label: sprints } |
| 55 | + sprints2 --> sprint1@{ shape: docs, label: "1" } |
| 56 | + sprint1 --> prep@{shape: docs, label: prep} |
| 57 | + sprint1 --> backlog@{shape: docs, label: backlog} |
| 58 | + sprint1 --> plan@{shape: docs, label: day-plan} |
| 59 | + sprint1 --> moduleSuccess@{shape: docs, label: success} |
| 60 | +``` |
| 61 | + |
| 62 | +## Adding Prep Work |
| 63 | + |
| 64 | +The `prep` directory contains an `index.md` file listing all files to be included with a module. Each entry requires two pieces of information: |
| 65 | + |
| 66 | +- `name` specifies the page's title in the page map |
| 67 | +- `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. |
| 68 | + |
| 69 | +Within `common-content` prep material is split across two directories: |
| 70 | + |
| 71 | +- `blocks` contains content which can be reused across different courses |
| 72 | +- `module` contains content specific to a particular module, subdivided by topic |
| 73 | + |
| 74 | +```mermaid |
| 75 | +--- |
| 76 | +title: common-content structure |
| 77 | +--- |
| 78 | +flowchart TD |
| 79 | + common@{ shape: docs, label: common-content } --> en@{ shape: docs, label: en } |
| 80 | + en --> blocks@{ shape: docs, label: blocks } |
| 81 | + en --> module@{ shape: docs, label: module } |
| 82 | +``` |
| 83 | + |
| 84 | +When adding new content: |
| 85 | + |
| 86 | +1. Create a new directory in the appropriate place. These can be nested within `blocks` or `modules`. |
| 87 | +2. In your directory create `index.md` |
| 88 | +3. Provide the appropriate front matter: |
| 89 | + |
| 90 | +```md |
| 91 | ++++ |
| 92 | +title = "Document Title" |
| 93 | +<!-- duration in minutes --> |
| 94 | +time = 120 |
| 95 | +<!-- learning objectives as strings. --> |
| 96 | +objectives = [ |
| 97 | + "Learning objective 1", |
| 98 | + "Learning objective 2", |
| 99 | + "Learning objective 3", |
| 100 | +] |
| 101 | +<!-- build config - no need to edit this --> |
| 102 | +[build] |
| 103 | + render = "never" |
| 104 | + list = "local" |
| 105 | + publishResources = false |
| 106 | ++++ |
| 107 | +``` |
| 108 | + |
| 109 | +4. Write your content using markdown. Notes on styling and using render hooks can be found in the [Common documentation](https://common.codeyourfuture.io/). |
| 110 | +5. Add the path to your content to `index.md` in the `prep` directory. |
| 111 | + |
| 112 | +If your content is loaded from an external GitHub url you can skip steps 1 and 2. |
| 113 | + |
| 114 | +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. |
| 115 | + |
| 116 | +### Code Examples |
| 117 | + |
| 118 | +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. |
| 119 | + |
| 120 | + |
| 121 | +## Adding Backlog Items |
| 122 | + |
| 123 | +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. |
| 124 | + |
| 125 | +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. |
| 126 | + |
| 127 | +To remove an item from a backlog you can close the relevant issue. |
| 128 | + |
| 129 | +> [!CAUTION] |
| 130 | +> Other internal systems reference these issues - every issue **must** have labels for `sprint`, `submission` and `priority`. |
| 131 | +
|
| 132 | +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. |
| 133 | + |
| 134 | + |
| 135 | +## Updating the Day Plan |
| 136 | + |
| 137 | +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: |
| 138 | + |
| 139 | +- Activities repeated across multiple classes (energisers, lunch breaks, etc.). These are stored in `common-content/en/blocks`. |
| 140 | +- Workshops for that class. |
| 141 | + |
| 142 | +Workshops can be defined in various places. Some are stored in `common-content/en/module` similar to prep content. |
| 143 | + |
| 144 | +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. |
| 145 | + |
| 146 | +Workshops may also be created in stand-alone repositories if needed. |
| 147 | + |
| 148 | + |
| 149 | +## Updating Success Criteria |
| 150 | + |
| 151 | +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. |
| 152 | + |
| 153 | +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. |
0 commit comments