├── CONTRIBUTING.md ├── LICENCE.md ├── README.md ├── git-config.md ├── git-setup.md ├── git.md ├── github.md ├── images ├── github-clone-url.png ├── github-commit.png ├── github-edit.png ├── github-editing.png ├── github-issue.png ├── github-new-project-init.png ├── github-new-project.png ├── github-new-repo.png ├── github-pull-request.png ├── github-signup.png ├── octocat.jpg └── view-edit-on-github.png ├── licensing.md ├── markdown.md ├── structure.md └── style.md /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | All contributions are assumed to be licensed under the same license as the source i.e. [CC BY-SA](http://creativecommons.org/licenses/by-sa/4.0/). This license must remain in all derivatives of this work. 4 | 5 | ## Issues 6 | 7 | If you find a mistake, bug or other problem, please [open an issue](https://github.com/raspberrypilearning/creating-resources/issues) in this repository. 8 | 9 | ## Pull Requests 10 | 11 | If you fix a mistake, bug or problem, or have something to contribute, please create a pull request for each modification. Please consider grouping modifications sensibly i.e. don't bundle typo fixes in the same pull request as code changes; instead, file them separately. 12 | 13 | Please note that sometimes there are pedagogical reasons for certain style conventions. Changes which make sense from a software engineering perspective, such as reducing duplication or making use of more advanced programming language features, may not be suitable for maintaining the intended educational value of the material. 14 | 15 | ## Derivatives 16 | 17 | The licence must remain in all derivatives of this work. 18 | 19 | ## Licence 20 | 21 | Unless otherwise specified, everything in this repository is covered by the following licence: 22 | 23 | [![Creative Commons License](http://i.creativecommons.org/l/by-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-sa/4.0/) 24 | 25 | ***Creating Resources*** by the [Raspberry Pi Foundation](http://www.raspberrypi.org) is licensed under a [Creative Commons Attribution 4.0 International Licence](http://creativecommons.org/licenses/by-sa/4.0/). 26 | 27 | Based on a work at https://github.com/raspberrypilearning/creating-resources 28 | -------------------------------------------------------------------------------- /LICENCE.md: -------------------------------------------------------------------------------- 1 | # Licence 2 | 3 | Unless otherwise specified, everything in this repository is covered by the following licence: 4 | 5 | [![Creative Commons License](http://i.creativecommons.org/l/by-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-sa/4.0/) 6 | 7 | ***Creating Resources*** by the [Raspberry Pi Foundation](http://www.raspberrypi.org) is licensed under a [Creative Commons Attribution 4.0 International Licence](http://creativecommons.org/licenses/by-sa/4.0/). 8 | 9 | Based on a work at https://github.com/raspberrypilearning/creating-resources 10 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Creating Resources 2 | 3 | A short guide for educators and trainers intending to create learning material on GitHub for their own use, for consideration on the [Raspberry Pi website](http://www.raspberrypi.org/resources/), or both. 4 | 5 | Before creating or submitting a resource, it is important to know what you're aiming to achieve, who the resource is for, how the information is presented, to what extent you would like to share the materials, and whether you would mind others adapting it to suit their own purpose. 6 | 7 | ## Teach, Learn or Make 8 | 9 | It is important to know what type of resource you're creating. On the Raspberry Pi website, our resources fall in to one of three categories: **Teach**, **Learn**, and **Make**. 10 | 11 | ### Teach 12 | 13 | *Teach* resources are schemes of work matching the English Computing curriculum, with features such as a programme of study, lesson plans, learning objectives, and learning outcomes. 14 | 15 | ### Learn 16 | 17 | *Learn* resources are materials which work well as a one-off lesson, workshop, or as an individual exercise. 18 | 19 | ### Make 20 | 21 | *Make* resources are materials which involve building or creating something physical, and usually involve hardware or creating multimedia. 22 | 23 | ## GitHub 24 | 25 | GitHub is a software projects hosting service; it's a kind of social networking site for code projects. It uses version-control software Git to manage changes in projects, and allows collaboration over the web. 26 | 27 | See our [GitHub Guide](github.md) to learn how to use GitHub to write and contribute to resources. 28 | 29 | ## Markdown 30 | 31 | Markdown is a plain-text formatting syntax. It's very simple, and it maintains its readability while offering a range of formatting options. Our documentation and educational resources are written in Markdown, and we encourage others to use it for any resources they write themselves and submit to us. 32 | 33 | See our [Markdown Guide](markdown.md) to learn how to write materials in this way. 34 | 35 | See our [Style Guide](style.md) to learn about our preferred methods of formatting Markdown. 36 | 37 | ## Structure 38 | 39 | There is a format to the repository of a Raspberry Pi resource. Some resources are larger projects than others, and require more structure and organisation to the contents. 40 | 41 | See our [Resource Structure Guide](structure.md) to learn how to organise the files and folders in your repository. 42 | 43 | ## Licensing 44 | 45 | At the Raspberry Pi Foundation, we want to maximise the potential reach and application of all the resources we create, so all our own materials are released under a [Creative Commons](http://creativecommons.org/) licence. 46 | 47 | Read our [Licensing Guide](licensing.md) to learn about Creative Commons and how to select a licence for your resource. 48 | 49 | ## Submissions 50 | 51 | If you intend to write a Raspberry Pi learning resource to share with the community, we recommend you follow our guidelines and submit to us to review and potentially include it on the website. 52 | 53 | Once you have your resource ready to submit, email the URL of the GitHub repository to [contributions@raspberrypi.org](mailto:contributions@raspberrypi.org). 54 | 55 | Alternatively, if you have resources prepared in another format we can use (Word document or text file - not PDF), you can send these to the same email address. Note that such submissions will take longer to process. 56 | 57 | We retain the right not to use contributions. 58 | 59 | ### Process 60 | 61 | If we decide to include your resource on our website, we will fork the project into the [raspberrypilearning](https://github.com/raspberrypilearning) GitHub organisation. We may make amendments to this copy, and yours will be left as it was, with the option of merging our changes into your original copy. 62 | 63 | At the time of writing there is currently no named attribution on our Resources page, but the name of the author is given on the project's front page. We intend to better highlight author and contributor names on the website in the near future. 64 | 65 | ## Contact 66 | 67 | Feel free to speak to us about resources, GitHub, licences and so on; we'll try to help with any queries. 68 | 69 | - [Ben Nuttall](https://github.com/bennuttall) 70 | - [Carrie Anne Philbin](https://github.com/missphilbin) 71 | 72 | ## Feedback 73 | 74 | Please let us know how you use GitHub in Education, how you use our resources, or how you feel we could improve our methods. 75 | 76 | ## Links 77 | 78 | ### Raspberry Pi 79 | 80 | - [Raspberry Pi](http://www.raspberrypi.org/) website 81 | - [Raspberry Pi](https://github.com/raspberrypi) on GitHub 82 | - [Raspberry Pi resources](http://www.raspberrypi.org/resources) 83 | - [Raspberry Pi Learning](https://github.com/raspberrypilearning) on GitHub 84 | - [Picademy homepage](http://www.raspberrypi.org/picademy) 85 | - [Picademy](https://github.com/picademy) on GitHub 86 | 87 | ### GitHub 88 | 89 | - [GitHub for Education](https://education.github.com) 90 | - [GitHub Help Pages](https://help.github.com/) 91 | 92 | ## Licence 93 | 94 | Unless otherwise specified, everything in this repository is covered by the following licence: 95 | 96 | [![Creative Commons License](http://i.creativecommons.org/l/by-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-sa/4.0/) 97 | 98 | ***Creating Resources*** by the [Raspberry Pi Foundation](http://www.raspberrypi.org) is licensed under a [Creative Commons Attribution 4.0 International Licence](http://creativecommons.org/licenses/by-sa/4.0/). 99 | 100 | Based on a work at https://github.com/raspberrypilearning/creating-resources 101 | -------------------------------------------------------------------------------- /git-config.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | A guide to configuring git and connecting to GitHub on the command line. 4 | 5 | ## Step 1: Set your identity 6 | 7 | First, set your identity in git so that your commits have author information attached. Enter the following two commands to set your name and email: 8 | 9 | ```bash 10 | git config --global user.name "Your Name" 11 | git config --global user.email username@email.com 12 | ``` 13 | 14 | ## Step 2: Check for existing SSH keys 15 | 16 | It's recommended that an SSH key is set up to authenticate with GitHub. If you don't do this you'll have to enter your username and password every time. 17 | 18 | First, check for existing SSH keys on your computer by showing the contents of the `.ssh` directory in your home folder: 19 | 20 | ```bash 21 | ls ~/.ssh 22 | ``` 23 | 24 | If you already see an `id_rsa` and `id_rsa.pub`, you have already created a key pair. If you know you created these, you can skip to Step 4; if you're unsure, you should delete these using the command `rm id_rsa*` and generate a new key. 25 | 26 | It may be the case that your `.ssh` folder does not contain keys (or you deleted them), or the folder does not exist (you'll see the error `ls: cannot access .ssh: No such file or directory`). If so, proceed to step 3. 27 | 28 | ## Step 3: Generate SSH keys 29 | 30 | Use the `ssh-keygen` command to generate a new SSH key: 31 | 32 | ``` 33 | ssh-keygen -t rsa -C "username@computer" 34 | ``` 35 | 36 | Be sure to identify the key with a descriptive name in the comment (`-C`) so you know which computer it belongs to; for example, `bob@raspberrypi` or `frank@laptop`. 37 | 38 | You'll see the following: 39 | 40 | ``` 41 | Generating public/private rsa key pair. 42 | # Enter file in which to save the key (/home/you/.ssh/id_rsa): 43 | ``` 44 | 45 | Press `Enter` to save the key to the default location. 46 | 47 | Next, you'll be prompted to enter a passphrase. Type this in and press `Enter`, or just press `Enter` to leave blank. 48 | 49 | Then add your new key to the `ssh-agent`: 50 | 51 | ```bash 52 | ssh-add ~/.ssh/id_rsa 53 | ``` 54 | 55 | Now you'll find `id_rsa` and `id_rsa.pub` files in your `.ssh` directory; these are your public and private RSA keys. **Never** share your private key. 56 | 57 | ## Step 4: Add your SSH key to GitHub 58 | 59 | Reveal the contents of your public key with the following command: 60 | 61 | ```bash 62 | cat ~/.ssh/id_rsa.pub 63 | ``` 64 | 65 | You will now paste your public key into GitHub which will validate against your private key. 66 | 67 | Sign in to [github.com](https://github.com/), go to your [Account Settings](https://github.com/settings/admin) and go to [SSH Keys](https://github.com/settings/ssh) in the left sidebar. 68 | 69 | Click `Add SSH Key` and enter a title to describe which computer the key belongs to, e.g. "Raspberry Pi" or "Ubuntu Laptop". 70 | 71 | Now paste the whole public key into the key field and click the `Add key` button. 72 | 73 | Return to the command line and test your SSH connection to GitHub: 74 | 75 | ```bash 76 | ssh -T git@github.com 77 | ``` 78 | 79 | You should see the message: 80 | 81 | ``` 82 | Hi ! You've successfully authenticated, but GitHub does not provide shell access. 83 | ``` 84 | 85 | If you have any issues, see [GitHub's help page](https://help.github.com/articles/generating-ssh-keys#step-4-test-everything-out) 86 | 87 | Now proceed to the [Using Git Guide](git.md). 88 | -------------------------------------------------------------------------------- /git-setup.md: -------------------------------------------------------------------------------- 1 | # Using Git 2 | 3 | A guide to using setting up a local git installation connected to GitHub. 4 | 5 | ## Installation 6 | 7 | Linux users can install the `git` package, e.g. `apt-get install git`. 8 | 9 | For other platforms, download from [git-scm.com/download](http://git-scm.com/download/). 10 | 11 | ## Graphical tools 12 | 13 | Windows and Mac users can use a GUI tool to manage their git repository locally, with GitHub integration built in: 14 | 15 | - [GitHub for Windows](https://windows.github.com/) 16 | - [GitHub for Mac](https://mac.github.com/) 17 | 18 | ## Command line 19 | 20 | Linux users should follow the [Command Line Git Guide](git.md). Windows and Mac users can also follow this guide, but note that setup is different and there will be slight variations in usage. 21 | -------------------------------------------------------------------------------- /git.md: -------------------------------------------------------------------------------- 1 | # Using Git 2 | 3 | A guide to using git on the command line. 4 | 5 | First, see the [Configuring Git Guide](git-config.md) to set up and connect to GitHub. 6 | 7 | ## Create a repository 8 | 9 | There are two ways to create a repository: on the command line, and on GitHub. 10 | 11 | `git init` requires you to create a repository on the command line and connect it to a GitHub repository (which you'll also need to create); whereas using `git clone` you only need to create the repository on GitHub then copy it to your computer, and easily push changes back to GitHub. 12 | 13 | ### git clone 14 | 15 | `git clone` is easier to use than `git init`, so new users should start here. 16 | 17 | 1. Sign in to [github.com](https://github.com/), click the plus icon in the top bar and go to `New repository`. 18 | 19 | ![GitHub New Repository](images/github-new-repo.png) 20 | 21 | 1. On the new repository page, fill in the project title and description and make sure to tick the `Initialize this repository with a README` box. 22 | 23 | ![GitHub Create Repository](images/github-new-project-init.png) 24 | 25 | 1. Go to the repository on GitHub and click the `SSH` toggle beneath the clone URL box on the right hand side beneath the tabs; if you did not set up an SSH key, click `HTTPS`. Click the copy icon to copy the URL. 26 | 27 | ![GitHub Clone URL](images/github-clone-url.png) 28 | 29 | 1. In the command line, enter `git clone` followed by the URL you just copied, i.e. `git@github.com:user/repo.git`. If you get an error on this step, see this [GitHub SSH error help page](https://help.github.com/articles/error-permission-denied-publickey). 30 | 31 | ### git init 32 | 33 | As an alternative to `git clone`, you can create the git repository on the command line using `git init`. 34 | 35 | 1. Create a directory for your new project with `mkdir projectname` and enter the folder with `cd projectname`. If the project you want to add to GitHub already exists, make sure the project files are in their own folder, then `cd` into it. 36 | 37 | 1. Enter `git init` to initialise a git repository in the folder. 38 | 39 | 1. Sign in to [github.com](https://github.com/), click the plus icon in the top bar and go to `New repository`. 40 | 41 | ![GitHub New Repository](images/github-new-repo.png) 42 | 43 | 1. On the new repository page, fill in the project title and description. Make sure not to tick the `Initialize this repository with a README` box. 44 | 45 | ![GitHub Create Repository](images/github-new-project.png) 46 | 47 | 1. Go to the repository on GitHub and click the `SSH` toggle beneath the clone URL box on the right hand side beneath the tabs; if you did not set up an SSH key, click `HTTPS`. Click the copy icon to copy the URL. 48 | 49 | ![GitHub Clone URL](images/github-clone-url.png) 50 | 51 | 1. Enter `git remote add github` followed by the URL you just copied, i.e. `git@github.com:user/repo.git`. 52 | 53 | ## Record changes to the repository 54 | 55 | ### Committing to the repository 56 | 57 | Whether you used `git clone` or `git init`, you can now add files to your git repository's index and commit them to track changes. 58 | 59 | 1. Enter `git add -A` to add all files in the directory, or use `git add file1 file2 file3` to explicitly add files and folders. Note this only notifies git of the filenames, not their contents. 60 | 61 | 1. Enter `git status` to see what files git is aware of. Use `git add` to add more. 62 | 63 | 1. Enter `git commit -am "Initial commit"`; this will commit all files to the repository and the state of the project will be saved in this form in the repository's history. The `-a` means "all" (i.e. commit all files) and the `m` is for the commit message which follows. If the commit message is not given, your default editor (probably Nano) will be opened for you to enter it there. 64 | 65 | 1. Further commits should be given a meaningful commit message and should be in the form of an instruction, such as `Add worksheet` or `Fix typo`. Commit messages are shown on GitHub in the project's history, with author information attached. 66 | 67 | ## Connect with GitHub 68 | 69 | ### Pushing to GitHub 70 | 71 | Once you're ready to put your changes on GitHub, you'll use `git push`. 72 | 73 | 1. Enter `git status` to check your changes are committed. You can perform multiple commits before pushing. 74 | 75 | 1. If you started with `git clone`, just enter `git push` to push your changes to GitHub. 76 | 77 | 1. If you used `git init`, you'll need to specify where to push to. Earlier you set up a remote location, and you can set this as the default remote location the first time you push. Use `git push -u github master`; this will set your upstream to the remote you named `github`. 78 | 79 | ### Pulling from GitHub 80 | 81 | To pull changes made on GitHub, use `git pull`. If changes are made to GitHub's version, you must use `git pull` to get your repository up to date before pushing. 82 | 83 | ## Other tools 84 | 85 | - [gitk](http://git-scm.com/docs/gitk) 86 | - Visual git repository browser tool 87 | - [meld](http://meldmerge.org/) 88 | - Visual diff tool 89 | -------------------------------------------------------------------------------- /github.md: -------------------------------------------------------------------------------- 1 | # Getting Started with GitHub 2 | 3 | A guide to getting started on GitHub, particularly for educators looking to contribute [resources for the Raspberry Pi website](http://www.raspberrypi.org/resources/) or otherwise use GitHub in Education. 4 | 5 | ![GitHub Octocat](images/octocat.jpg) 6 | 7 | ## Sign up to GitHub 8 | 9 | Go to [github.com](https://github.com/) and sign up. You'll need to select a username which will determine your profile's URL, i.e. `github.com/username`, and provide an email address and password. 10 | 11 | ![Sign up to GitHub](images/github-signup.png) 12 | 13 | ### Your profile page 14 | 15 | Once you're signed up, your profile page will be public at `github.com/username`. This page will list your repositories as you create them, some biographical information, a visual representation of your contributions, and a feed of your recent activity. 16 | 17 | You may wish to add a picture and fill in the basic biography fields on your [profile settings](https://github.com/settings/profile) page. 18 | 19 | ## Locate our repositories 20 | 21 | You will find all of the repositories that contain our learning resources at [github.com/raspberrypilearning](https://github.com/raspberrypilearning). Alternatively, locate the resource on our website and scroll down to the footer to see the `View/edit this page on GitHub` link. 22 | 23 | ![View/edit this page on GitHub](images/view-edit-on-github.png) 24 | 25 | ### Issues 26 | 27 | If you find a problem with the content of one of our resources, such as a bug in the code or a poorly explained instruction, you can report this to us as an issue on the resource's GitHub repository. 28 | 29 | To do this, navigate to the repository in question, go to the `Issues` tab on the right hand side and click the `New Issue` button. 30 | 31 | Fill in the issue title and write as much detail as you can for us to identify the problem or reproduce the bug. One of our team will then look into the issue and attempt to resolve it. Some issues are easy to resolve, and can be fixed and closed swiftly; some take time to identify or reproduce and fix; some issues we consider invalid, such as a recommendation we believe reduces the intended educational value. A conversation may arise on an issue, where our team aim to determine the nature of the problem and communication with the user would be useful. 32 | 33 | You can use Markdown to add links, emphasis and so forth. It is very useful to include a link to the file you're talking about, so that the reviewer can head straight over to look at the problem. 34 | 35 | ![View/edit this page on GitHub](images/github-issue.png) 36 | 37 | Be sure to read the contributing policy for a repository before opening an issue. You'll find this in the `CONTRIBUTING.md` file in the root of the repository. 38 | 39 | ### Editing 40 | 41 | While browsing a file on GitHub, you will see an `Edit` button: 42 | 43 | ![GitHub's Edit button](images/github-edit.png) 44 | 45 | Clicking this will create a copy of the repository in your name; this process is called *forking*. For example, if you forked `github.com/raspberrypilearning/push-button-stop-motion` you would find your copy at `github.com/yourusername/push-button-stop-motion`, with the full history of the project available. Any changes made to your copy will not be reflected in the original repository until you request them to be merged, and the project maintainer does so. 46 | 47 | ![Editing on GitHub](images/github-editing.png) 48 | 49 | Make your changes in the GitHub editor, enter a brief commit message and your version will be saved when you press `Commit changes`: 50 | 51 | ![GitHub commit message](images/github-commit.png) 52 | 53 | Commit messages should be given in the form of an instruction like `Add note about camera module` or `Update NOOBS version number` rather than in the past tense. 54 | 55 | #### Pull requests 56 | 57 | A pull request is the action of sending your changes to your fork of someone else's project back to the original author. They can then review your changes and have the option of accepting or denying your request. 58 | 59 | ![A Pull Request on GitHub](images/github-pull-request.png) 60 | 61 | Be sure to read the contributing policy for a repository before creating a pull request. You'll find this in the `CONTRIBUTING.md` file in the root of the repository. 62 | 63 | ### Contributing new resources 64 | 65 | To create a new resource project, or to add an existing resource to GitHub, click the `+` icon in the navigation bar on GitHub, and select `New Repository`: 66 | 67 | ![Creating a new Repository on GitHub](images/github-new-repo.png) 68 | 69 | Follow the [Markdown guide](markdown-guide.md) and [structure guide](structure-guide.md) to learn how to write and format the material appropriately. 70 | 71 | #### Submitting 72 | 73 | See the [Submission notes](README.md#submissions) for more information. 74 | 75 | ## Using Git offline 76 | 77 | GitHub's web interface can be used for a great deal of tasks; however, some will require using git on your computer, either with a GUI or using the command line. 78 | 79 | GitHub's editor is suitable for small additions and modifications; if writing substantial amounts of material, it is advisable to use an offline editor and commit using git on your computer. 80 | 81 | See the [Git guide](git.md) for more information. 82 | -------------------------------------------------------------------------------- /images/github-clone-url.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-clone-url.png -------------------------------------------------------------------------------- /images/github-commit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-commit.png -------------------------------------------------------------------------------- /images/github-edit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-edit.png -------------------------------------------------------------------------------- /images/github-editing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-editing.png -------------------------------------------------------------------------------- /images/github-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-issue.png -------------------------------------------------------------------------------- /images/github-new-project-init.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-new-project-init.png -------------------------------------------------------------------------------- /images/github-new-project.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-new-project.png -------------------------------------------------------------------------------- /images/github-new-repo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-new-repo.png -------------------------------------------------------------------------------- /images/github-pull-request.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-pull-request.png -------------------------------------------------------------------------------- /images/github-signup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/github-signup.png -------------------------------------------------------------------------------- /images/octocat.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/octocat.jpg -------------------------------------------------------------------------------- /images/view-edit-on-github.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/raspberrypilearning/creating-resources/75bbeab34c8d7ffd953d8694db32f13bcf756b42/images/view-edit-on-github.png -------------------------------------------------------------------------------- /licensing.md: -------------------------------------------------------------------------------- 1 | # Licences 2 | 3 | At the Raspberry Pi Foundation, we want to maximise the potential reach and application of all the resources we create, so all our own materials are released under a [Creative Commons](http://creativecommons.org/) licence. 4 | 5 | > A CC [Creative Commons] license is used when an author wants to give people the right to share, use and build upon a work that they have created. 6 | > 7 | > ~ [Wikipedia](http://en.wikipedia.org/wiki/Creative_Commons_license) 8 | 9 | The licence we use is [CC BY-SA](http://creativecommons.org/licenses/by-sa/4.0/) (attribution and share-alike), which is the licence used by Wikipedia. 10 | 11 | [![Creative Commons License](http://i.creativecommons.org/l/by-sa/4.0/88x31.png)](http://creativecommons.org/licenses/by-sa/4.0/) 12 | 13 | Read more about [our use of Creative Commons](http://www.raspberrypi.org/creative-commons/). 14 | 15 | ## Choosing a licence 16 | 17 | You are free to select whatever licence you feel comfortable with, and you are entitled to use the methods described in this document without sharing your work. If you would like to share your resources with other educators, we would recommend you follow our lead and use the CC BY-SA licence as above. 18 | 19 | Submissions of resources are appreciated, provided they are available under a Creative Commons license such as CC BY-SA. Please [contact us](http://www.raspberrypi.org/contact-us/) for more information. 20 | 21 | ## Software licences 22 | 23 | Creative Commons covers use of creative works such as written material, music or photography. Software projects use a different set of licences which state the use and distribution of software. Such licences are suitable for software libraries or products/services, but small examples of code used in the context of a learning resource can be covered by the Creative Commons licence relating to the creative works. 24 | 25 | In most cases, software licences would be unnecessary in learning resources, but if you created a general-purpose software library to go with your resource, you should look at choosing an appropriate licence for the library. 26 | 27 | For example, Sonic Pi uses the [MIT Licence](https://github.com/samaaron/sonic-pi/blob/master/LICENSE.md) and the `python-picamera` module uses the [BSD Licence](https://github.com/waveform80/picamera/blob/master/LICENSE.txt). 28 | 29 | Refer to [choosealicense.com](http://choosealicense.com/) for more information, or feel free to [contact us](http://www.raspberrypi.org/contact-us/). 30 | -------------------------------------------------------------------------------- /markdown.md: -------------------------------------------------------------------------------- 1 | # Raspberry Pi Learning Markdown Guide 2 | 3 | Markdown Guide for Raspberry Pi Learning Resources 4 | 5 | ## What is Markdown? 6 | 7 | Markdown is a plain-text formatting syntax. It's very simple, and it maintains its readability while offering a range of formatting options. 8 | 9 | See the [Markdown Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) on GitHub for reference. 10 | 11 | An example Markdown file might look like this: 12 | 13 | ``` 14 | # Title 15 | 16 | Intro paragraph goes here 17 | 18 | Here is a list of things: 19 | 20 | - Raspberry Pi 21 | - USB mouse 22 | - USB keyboard 23 | - Power supply 24 | 25 | Here is some more text 26 | ``` 27 | 28 | which would render like so: 29 | 30 | ># Title 31 | > 32 | >Intro paragraph goes here 33 | > 34 | >Here is a list of things: 35 | > 36 | >- Raspberry Pi 37 | >- USB mouse 38 | >- USB keyboard 39 | >- Power supply 40 | > 41 | >Here is some more text 42 | 43 | ### Why Markdown? 44 | 45 | Markdown is easy to write, there's not much to learn to get going, and you get an instant visual representation of simply formatted works. 46 | 47 | As stated in the [Markdown project's philosophy](http://daringfireball.net/projects/markdown/syntax#philosophy): 48 | 49 | > Markdown is intended to be as easy-to-read and easy-to-write as is feasible. 50 | > 51 | > Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. 52 | 53 | Using Markdown in a repository on GitHub allows changes to be managed as the contents evolve. Every revision can be returned to at any point, and it is easy to view a visual difference between any two revisions. 54 | 55 | ## Markdown basics 56 | 57 | ### Headings 58 | 59 | Headings are denoted by the hash symbol. There are six level headings, which are hierarchical: 60 | 61 | ``` 62 | # Header 1 63 | ## Header 2 64 | ### Header 3 65 | #### Header 4 66 | ##### Header 5 67 | ###### Header 6 68 | ``` 69 | 70 | ### Emphasis 71 | 72 | Emphasis (italics) uses `*asterisks*`: 73 | 74 | *asterisks* 75 | 76 | Strong emphasis (bold) uses `**double asterisks**`: 77 | 78 | **double asterisks** 79 | 80 | Use both together (bold italic) with `***triple asterisks***` or combined `***bold italic* and just bold**`. 81 | 82 | ***triple asterisks*** 83 | 84 | or 85 | 86 | ***bold italic* and just bold** 87 | 88 | Strikethrough uses two tildes `~~like so~~`: 89 | 90 | ~~like so~~ 91 | 92 | ### Lists 93 | 94 | #### Unordered lists (bullets) 95 | 96 | Unordered lists simply use a hyphen at the start of each line like so: 97 | 98 | ``` 99 | - Python 100 | - Scratch 101 | - Sonic Pi 102 | - Minecraft 103 | ``` 104 | 105 | which renders like so: 106 | 107 | - Python 108 | - Scratch 109 | - Sonic Pi 110 | - Minecraft 111 | 112 | #### Ordered lists (numbered) 113 | 114 | Ordered lists simply use a number and a dot at the start of each line like so: 115 | 116 | ``` 117 | 1. Python 118 | 2. Scratch 119 | 3. Sonic Pi 120 | 4. Minecraft 121 | ``` 122 | 123 | which renders like so: 124 | 125 | 1. Python 126 | 2. Scratch 127 | 3. Sonic Pi 128 | 4. Minecraft 129 | 130 | You can also just repeat `1.` at the beginning of each line, and the numbers will be automatically generated as you add more. This is especially useful for adding items in the middle of a list, as it saves you renumbering the items: 131 | 132 | ``` 133 | 1. Python 134 | 1. Scratch 135 | 1. Sonic Pi 136 | 1. Minecraft 137 | ``` 138 | 139 | 1. Python 140 | 1. Scratch 141 | 1. Sonic Pi 142 | 1. Minecraft 143 | 144 | #### Nested lists 145 | 146 | You can nest items in ordered or unordered lists, or even combine the two, by indenting to create a sub-list like so: 147 | 148 | ``` 149 | - Hardware 150 | 1. Raspberry Pi 151 | 1. Camera module 152 | - Software 153 | 1. Python Picamera 154 | 1. FFMPEG 155 | ``` 156 | 157 | - Hardware 158 | 1. Raspberry Pi 159 | 1. Camera module 160 | - Software 161 | 1. Python Picamera 162 | 1. FFMPEG 163 | 164 | Sub-lists continue with further indentation. 165 | 166 | #### Paragraphs in between list items 167 | 168 | If you need to include further text in between list items, indent the text with four spaces. This will allow your list to continue, so that numbering in an ordered list will not break sequence. For example: 169 | 170 | ``` 171 | 1. Plug in your mouse and keyboard 172 | 173 | These go in the USB ports along the short side of the Raspberry Pi opposite the SD card slot 174 | 175 | 1. Connect your HDMI cable 176 | 177 | This goes in the HDMI port on the long side of the Raspberry Pi 178 | ``` 179 | 180 | 1. Plug in your mouse and keyboard 181 | 182 | These go in the USB ports along the short side of the Raspberry Pi opposite the SD card slot 183 | 184 | 1. Connect your HDMI cable 185 | 186 | This goes in the HDMI port on the long side of the Raspberry Pi 187 | 188 | 189 | ### Links 190 | 191 | Links are created by giving the link text in square brackets, immediately followed by round brackets containing the link URL: 192 | 193 | ``` 194 | Check out the [Raspberry Pi](http://www.raspberrypi.org/) website 195 | ``` 196 | 197 | Check out the [Raspberry Pi](http://www.raspberrypi.org/) website 198 | 199 | You can also link to other pages in the same repository: 200 | 201 | ``` 202 | See the [worksheet](worksheet.md) for this project 203 | ``` 204 | 205 | See the [worksheet](worksheet.md) for this project 206 | 207 | This would link to the `worksheet.md` file in the same folder as the current document. To go into another folder use the following format: 208 | 209 | ``` 210 | See the [Lesson 1 worksheet](lesson-1/worksheet.md) 211 | ``` 212 | 213 | See the [Lesson 1 worksheet](lesson-1/worksheet.md) 214 | 215 | This would link to the `worksheet.md` file in the `lesson-1` folder, provided the folder is at the same level as the current document. 216 | 217 | To go back up a level, use relative links: 218 | 219 | ``` 220 | See the [project requirements](../requirements.md) 221 | ``` 222 | 223 | See the [project requirements](../requirements.md) 224 | 225 | `../` denotes going back up one level. To go back up two levels: 226 | 227 | ``` 228 | See the [project requirements](../../requirements.md) 229 | ``` 230 | 231 | ### Images 232 | 233 | To include an image in a Markdown document, use the link syntax with a leading exclamation mark. Write a brief description of the image in the square brackets. 234 | 235 | ``` 236 | ![Raspberry Pi logo](http://www.raspberrypi.org/wp-content/uploads/2011/10/Raspi-PGB001-150x150.png) 237 | ``` 238 | 239 | ![Raspberry Pi logo](http://www.raspberrypi.org/wp-content/uploads/2011/10/Raspi-PGB001-150x150.png) 240 | 241 | You can also include images inside the repository; this is a good idea as they're then self-contained. You can refer to them relatively: 242 | 243 | ``` 244 | ![Raspberry Pi logo](raspberrypi.png) 245 | ``` 246 | 247 | or in another folder: 248 | 249 | ``` 250 | ![Raspberry Pi logo](../images/raspberrypi.png) 251 | ``` 252 | 253 | #### Images as links 254 | 255 | You can make an image into a link by wrapping it in square brackets as per the normal link syntax: 256 | 257 | ``` 258 | [![Raspberry Pi logo](raspberrypi.png)](http://www.raspberrypi.org/) 259 | ``` 260 | 261 | ### Code blocks 262 | 263 | Code blocks are used to show snippets of code in the context of some surrounding text. 264 | 265 | Code blocks are denoted by three back-ticks on separate lines either side, like so: 266 | 267 | 
```
268 | for i in range(10):
269 |     print(i)
270 | ```
271 | 272 | ``` 273 | for i in range(10): 274 | print(i) 275 | ``` 276 | 277 | Optionally, you can provide the language of the code used in the block, for syntax highlighting: 278 | 279 | 
```python
280 | for i in range(10):
281 |     print(i)
282 | ```
283 | 284 | ```python 285 | for i in range(10): 286 | print(i) 287 | ``` 288 | 289 | #### Inline code blocks 290 | 291 | You can refer to code or technical keywords inline (i.e. in a sentence) with single back-ticks: 292 | 293 | ``` 294 | Install the package `python-picamera` to access the camera directly from Python. 295 | ``` 296 | 297 | Install the package `python-picamera` to access the camera directly from Python. 298 | 299 | No syntax highlighting is available for inline code blocks. 300 | 301 | ### Block quotes 302 | 303 | You can format text as a block quote by beginning each line with a `>` like so: 304 | 305 | ``` 306 | >The Raspberry Picademy is a free professional development experience for primary and secondary teachers, initially for those here in the UK. 307 | ``` 308 | 309 | >The Raspberry Picademy is a free professional development experience for primary and secondary teachers, initially for those here in the UK. 310 | 311 | This is useful for quoting text from a web page, book, or documentation. 312 | 313 | It is good practice to cite the quote, simply with a link back to the origin if it is online, or another suitable reference: 314 | 315 | ``` 316 | >This package provides a pure Python interface to the Raspberry Pi camera module for Python 2.7 (or above) and Python 3.2 (or above). 317 | > 318 | >~ [Python Picamera Documentation](http://picamera.readthedocs.org/en/release-1.5/index.html) by [Dave Jones](https://github.com/waveform80) 319 | ``` 320 | 321 | >This package provides a pure Python interface to the Raspberry Pi camera module for Python 2.7 (or above) and Python 3.2 (or above). 322 | > 323 | >~ [Python Picamera Documentation](http://picamera.readthedocs.org/en/release-1.5/index.html) by [Dave Jones](https://github.com/waveform80) 324 | 325 | ### Tables 326 | 327 | It is possible to tabulate data in Markdown with the use of pipes (`|`) to denote columns: 328 | 329 | ``` 330 | | Workshop | Language | Leader | 331 | | ---------- |:---------:| -----------:| 332 | | Sonic Pi | Ruby | Carrie Anne | 333 | | Picamera | Python | Ben | 334 | | Minecraft | Python | Craig | 335 | ``` 336 | 337 | | Workshop | Language | Leader | 338 | | ---------- |:---------:| -----------:| 339 | | Sonic Pi | Ruby | Carrie Anne | 340 | | Picamera | Python | Ben | 341 | | Minecraft | Python | Craig | 342 | 343 | Note the use of colons to align columns. 344 | 345 | Use of pipes at the edges and alignment of columns is not necessary for the output, but it aids readability in the Markdown: 346 | 347 | ``` 348 | A | B | C 349 | :-: | :-: | :-: 350 | *italic* | `code` | **bold** 351 | 1 | 2 | 3 352 | ``` 353 | 354 | A | B | C 355 | :-: | :-: | :-: 356 | *italic* | `code` | **bold** 357 | 1 | 2 | 3 358 | 359 | Note the use of Markdown inside tables. 360 | 361 | ### Horizontal rule 362 | 363 | Horizontal rules can be used by inserting a line with three or more hyphens like so: 364 | 365 | ``` 366 | --- 367 | ``` 368 | 369 | --- 370 | 371 | ### Line breaks 372 | 373 | Paragraphs are formed by the presence of blank lines around text, and many other formatting styles in Markdown are affected by line breaks. 374 | 375 | ``` 376 | This is a single sentence followed by a blank line 377 | 378 | This is another sentence followed by a blank line 379 | 380 | This is three lines 381 | without a gap 382 | between each line 383 | ``` 384 | 385 | This is a single sentence followed by a blank line 386 | 387 | This is another sentence followed by a blank line 388 | 389 | This is three lines 390 | without a gap 391 | between each line 392 | 393 | If you want a paragraph, use new lines on either side of your text. 394 | 395 | If something doesn't quite look right in the preview window, try adding or removing new lines around it to achieve the desired formatting. 396 | 397 | 398 | ### Anchors 399 | 400 | If you require anchors to point at a particular section of a page, use an empty HTML `` element with a `name` attribute as reference, usually above a heading: 401 | 402 | ``` 403 | 404 | ## Raspberry Pi 405 | ``` 406 | 407 | This will allow you to refer to that section of the page by appending `#raspberrypi` to the URL. 408 | 409 | You can create a link to an anchor on the same page by referencing the hash link: 410 | 411 | ``` 412 | [Raspberry Pi](#raspberrypi) 413 | ``` 414 | 415 | or on another page with the relative or full URL: 416 | 417 | ``` 418 | [Raspberry Pi](../#raspberrypi) 419 | [Anchors](https://github.com/raspberrypilearning/creating-resources/markdown-guide.md#anchors) 420 | ``` 421 | 422 | --- 423 | 424 | *Based on [adam-p](https://github.com/adam-p)'s [Markdown Cheat Sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)* 425 | 426 | ## Markdown editors 427 | 428 | If you're using git on your computer rather than the GitHub editor, you can use a simple text editor. However, it can be useful to use a desktop Markdown editor with a preview pane. Here is a selection: 429 | 430 | - [ReText](https://launchpad.net/retext) for Linux (`apt-get install retext`) 431 | - [Mou](http://mouapp.com/) for Mac 432 | - [MarkdownPad](http://markdownpad.com/) for Windows 433 | - [StackEdit](https://stackedit.io/) - an online editor 434 | -------------------------------------------------------------------------------- /structure.md: -------------------------------------------------------------------------------- 1 | # Repository structure 2 | 3 | A typical **Learn** or **Make** resource repository may take the following format: 4 | 5 | - README.md 6 | - An index page introducing the material and the purpose of the exercise, providing details of any installation, setup instructions, and equipment required. 7 | - worksheet.md 8 | - A worksheet containing the instructions for the exercise, broken down into appropriate steps. 9 | - LICENCE.md 10 | - Details of the licence of the materials. 11 | - CONTRIBUTING.md 12 | - Information for contributors to the materials. 13 | 14 | The repository may also include a folder for code files, scripts and other downloadable assets, and may contain an images folder for any images embedded in the information pages or worksheets. Multiple worksheets can be used, and should be linked to from the index page. 15 | 16 | A typical **Teach** resource repository may contain an overall index page along with several folders containing similar contents to the **Learn** and **Make** resources, with more detail and presented within a greater structure. 17 | -------------------------------------------------------------------------------- /style.md: -------------------------------------------------------------------------------- 1 | # Raspberry Pi Learning style guide 2 | 3 | ## Headings 4 | 5 | The page title should be given as a top-level heading, and this should be the only top-level heading on the page. 6 | 7 | Second-level headings should reflect the sections of the document, and third-level headings should be used for sub-headings under these sections. Use further headings hierarchically if needed. 8 | 9 | Ensure a space is given after the hashes, i.e. `# Title` rather than `#Title`. 10 | 11 | ## Emphasis 12 | 13 | Strong emphasis (bold) should not be used as headings; use headings instead. Only use bold or italics to emphasise a word or some words in a sentence, as appropriate. 14 | 15 | ## Lists 16 | 17 | ### Unordered lists 18 | 19 | Always use a single hyphen followed by a single space, optionally with a line space between each item for longer items. 20 | 21 | ### Ordered lists 22 | 23 | Always precede each list item with a `1.` and allow automatic numbering to take effect. This makes it easier for collaborators to add list items in the middle without having to renumber them. 24 | 25 | ### Nested lists 26 | 27 | Use four spaces to indent a sub-list. 28 | 29 | ### Paragraphs in between list items 30 | 31 | If you need to include further text in between list items, indent the text with four spaces. This will allow your list to continue, so that numbering in an ordered list will not break sequence. Ensure list numbering is not unintentionally broken. 32 | 33 | ## Links 34 | 35 | Use links as described in the [Raspberry Pi Learning Markdown Guide](markdown.md). Check relative links are correct and be sure to update them if you change file or folder names, or move files to a new location. 36 | 37 | Try to use sensible link text accurately describing the link, e.g. `Check out [Raspberry Pi on GitHub](https://github.com/raspberrypi)` is better than `[Click here] to see Raspberry Pi on GitHub`. 38 | 39 | ### Relative links with a leading slash 40 | 41 | You may be familiar with the use of a leading `/` to link relatively from the root, rather than use a series of `../` to go back the correct number of levels; for instance, the path `/worksheet.md` would always point at the `worksheet.md` file at the root of the repository. 42 | 43 | This is a useful and valid technique; however, as resources are copied on to the Raspberry Pi website, the leading `/` would refer to the root of the website, not the root of the project. Therefore, it is advised that you only use relative links with `../`. 44 | 45 | ## Images 46 | 47 | It is good practice to have an `images` folder in the root of the repository which contains all the images used in the project. You can then refer to images relatively when you include them in a document. 48 | 49 | For larger projects, you may wish to use an `image` folder in each folder inside the repository. For example, if you have a folder on a scheme of work containing each lesson's documents and assets, you may wish to keep images used in each lesson in their respective `image` folders. 50 | 51 | Note that GitHub does not currently support uploading of images, so you would have to use a Git client on your PC rather than directly in the browser. 52 | 53 | ## Code blocks 54 | 55 | Use code blocks and syntax highlighting where possible. Both GitHub and the Raspberry Pi website support many languages. Be sure to use the correct language alias; common ones are `python`, `ruby`, `php`, `bash` and `javascript`. 56 | 57 | ### Inline code blocks 58 | 59 | It's recommended you use inline code blocks for language keywords, code snippets and some technical things like package names. For example, "Install the package `python-picamera` to access the camera directly from Python" and "Press `Ctrl + S` to save". 60 | 61 | ## Tables 62 | 63 | Where necessary, tables can be used. It is recommended tables are not too long, and the neat layout is preferred to aid readability. 64 | 65 | ## Horizontal rule 66 | 67 | Horizontal rules should be used sparingly. 68 | 69 | ## Line breaks 70 | 71 | Use newlines around text to render as paragraphs, unless the opposite is required. It's generally recommended to use newlines to separate all parts of content in Markdown form, as this aids readability. Unless newlines hinder the desired effect, please use them at all times. 72 | 73 | ## Anchors 74 | 75 | If you require anchors to point at a particular section of a page, use an empty HTML `` element with a `name` attribute. 76 | 77 | Note that GitHub applies anchors to headings automatically, but in order for them to be used on the Raspberry Pi site they will need to be explicitly added. 78 | 79 | ## Alternatives 80 | 81 | There are alternative methods to achieving the required formatting to the methods shown in this document. These have been deliberately left out here, as we would prefer those writing materials for our use to follow the same format to make collaboration and editing easier for all. 82 | --------------------------------------------------------------------------------