From ebd0ed1cde024a61968c064fa841696c865b435c Mon Sep 17 00:00:00 2001 From: Greg Wilson Date: Wed, 1 Apr 2015 09:23:58 -0400 Subject: [PATCH] Updating based on feedback --- FAQ.md | 2 +- LAYOUT.md | 59 ++++++++++++++++++++++++--------------------- README.md | 67 ++++++++++++++++++++++++++++++++------------------- motivation.md | 6 ++--- 4 files changed, 77 insertions(+), 57 deletions(-) diff --git a/FAQ.md b/FAQ.md index 33da082..60e6b66 100644 --- a/FAQ.md +++ b/FAQ.md @@ -12,7 +12,7 @@ [file an issue](https://github.com/swcarpentry/lesson-template/issues?q=is%3Aopen+is%3Aissue) or [mail us](mailto:admin@software-carpentry.org). -* *Why does the lesson repository have to be created using import? Why not fork `lesson-template` on GitHub?* +* *Why does the new lesson's repository have to be created using import? Why not fork `lesson-template` on GitHub?* Because any particular user can only have one fork of a repository, but instructors frequently need to work on several workshops at once. diff --git a/LAYOUT.md b/LAYOUT.md index 9ab3c9f..e2b1ec9 100644 --- a/LAYOUT.md +++ b/LAYOUT.md @@ -336,41 +336,40 @@ random number generation is outside the scope of the lesson, ## Motivational Slides -Every lesson must include a short slide deck suitable for a short +Every lesson must include a short slide deck in `motivation.md` suitable for a short presentation (3 minutes or less) that the instructor can use to explain to learners how knowing the subject will help them. The slides must -be laid out like this: +use level-2 headings as slide titles, but may use anything within the slide: --- layout: slides title: Lesson Title subtitle: Motivation --- -
- ## Why This Topic? -
+ ## Our Mission -
- ## Some Other Point -
+ We make scientists and engineering more productive + by teaching them basic computing skills. -**Notes:** + ## The Problem + + - Surveyed 1972 scientists in 2008. + - "How do you use computers?" + - "How did you learn what you know?" -1. This is the one place where we *must* use HTML tags in our Markdown - (to delimit slides). Everything inside the section markers should - be Markdown if possible. +**Notes:** -2. We use [deck.js](http://imakewebthings.com/deck.js/) for our slides +1. We use [deck.js](http://imakewebthings.com/deck.js/) for our slides as it is simpler and prettier than alternatives like [reveal.js](http://lab.hakim.se/reveal-js/). -3. For examples of slideshows, please see the +2. For examples of slideshows, please see the [slideshow repository](https://github.com/swcarpentry/slideshows). ## Reference Guide -The reference guide is a cheat sheet for learners to print, doodle on, +The reference guide in `reference.md` is a cheat sheet for learners to print, doodle on, and take away. Its format is deliberately unconstrained for now, since we'll need to see a few before we can decide how they ought to be laid out (or whether they need to be laid out the same way at all). @@ -395,32 +394,36 @@ a definition list: ## Discussion Page -The discussion page +The discussion page in `discussion.md` is meant to contain links to +further reading, supplementary material that classes usually won't +get to, and so on. Sections must use level-2 headings, but the +content is otherwise unconstrained: --- layout: page title: Lesson Title subtitle: Discussion --- - * First point of general discussion. + ## Something That May Be Useful + + Paragraphs of general discussion - This may span several paragraphs. + ## Something Else - * Second point of general discussion. + More general discussion, with links. -Note: the discussion page is not meant to be more lesson material, so -it should not contain challenges and the like. Instead, it should -give pointers to other lessons and tools that learners might find -useful, etc. Its format is deliberately vague for now: once we have -more experience with our lesson template, we will provide more -guidance on how to lay out this file. Until then, please do whatever -feels best. +Note: the discussion page is not lesson material, so it should not +contain challenges and the like. Its format is deliberately vague for +now: once we have more experience with our lesson template, we will +provide more guidance on how to lay out this file. Until then, please +do whatever feels best. ## Instructor's Guide Learners may go through lessons outside of class, so it seems best to -keep material for instructors in a separate document, rather than -interleaved in the lesson itself. Its structure is: +keep material for instructors in a separate document called +`instructors.md`, rather than interleaved in the lesson itself. Its +structure is: --- layout: page diff --git a/README.md b/README.md index 9e75b1b..444cef8 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ lesson-example ============== -This repository is an example of a lesson created using -the [Software Carpentry][swc] [lesson template][swc-lesson-template]. +This repository shows how to create a lesson using +the [Software Carpentry][swc] [lesson template][swc-lesson-template], +and is itself an example of the use of that template. 1. Do *not* fork this repository directly on GitHub. Instead, please follow the instructions below @@ -12,10 +13,14 @@ the [Software Carpentry][swc] [lesson template][swc-lesson-template]. 2. Once you have created the repository, please go through [the layout instructions](LAYOUT.md) to format your lesson. -Please *do your work in your repository's `gh-pages` branch*, -since that is what is [automatically published as a website by GitHub](https://help.github.com/articles/creating-project-pages-manually/). +3. Please keep the master copy of your lesson in your repository's `gh-pages` branch, + since that is what is + [automatically published as a website by GitHub](https://help.github.com/articles/creating-project-pages-manually/). + To simplify reviewing, + please make changes in feature branches + and then submit pull requests against the `gh-pages` branch of your lesson's repository. -## Manual Setup +## Creating Your Lesson's Repository We will assume that your user ID is `gvwilson` and the name of your lesson is `data-cleanup`. @@ -41,33 +46,33 @@ lesson is `data-cleanup`. When the process is done, you can click "Continue to repository" to visit your newly-created repository. -**Note:** -some people have had intermittent errors during the import process, -possibly because of the network timing out. -If you experience a problem, please re-try; -if the problem persists, -please [get in touch](#getting-and-giving-help). - 7. Clone your newly-created repository to your desktop: ~~~ - $ git clone -b gh-pages git@github.com:gvwilson/data-cleanup.git + $ git clone -b gh-pages https://github.com/gvwilson/data-cleanup.git ~~~ -8. Go into that directory using + Note that the URL for your lesson will be different than the one above. + +8. Go into that directory using: ~~~ $ cd data-cleanup ~~~ + Note that the name of your directory will be different, + since your lesson probably won't be called `data-cleanup`. + 9. Manually add the lesson template repository as a remote called `template`: ~~~ - $ git remote add template git@github.com:swcarpentry/lesson-template.git + $ git remote add template https://github.com/swcarpentry/lesson-template.git ~~~ This will allow you to pull in changes made to the template, such as improvements to our CSS style files. + (Note that the user name above is `swcarpentry`, *not* `gvwilson`, + since you are adding the master copy of the template as a remote.) 10. Create and edit files as explained in [Lesson Layout](LAYOUT.md), @@ -96,17 +101,25 @@ please [get in touch](#getting-and-giving-help). $ git push origin gh-pages ~~~ -13. Tell us where your lesson is so that we can add it to +13. [Tell us](#getting-and-giving-help) where your lesson is so that we can add it to [the Software Carpentry lessons page][swc-lessons-page]. **Note:** SSH cloning (rather than the HTTPS cloning used above) will also work for those who have set up SSH keys with GitHub. **Note:** Once a lesson has been created, please submit changes -for review as pull requests that contain _only the modified Markdown files_, -and _not_ the re-generated HTML. This simplifies review considerably, +for review as pull requests that contain *only the modified Markdown files*, +and *not* the re-generated HTML. This simplifies review considerably, since each change appears only once. Once the change has been approved, -the lesson maintainer(s) will re-generate the HTML and merge it. +the lesson maintainer(s) will merge the pull request, re-generate the HTML +locally, and pus that to GitHub. + +**Note:** +some people have had intermittent errors during the import process, +possibly because of the network timing out. +If you experience a problem, please re-try; +if the problem persists, +please [get in touch](#getting-and-giving-help). ## Dependencies @@ -156,8 +169,8 @@ We organize our lessons in a standard way so that: ## Why Is This Example (and Documentation) Separate from the Template? -We want it to be easy for authors to merge changes to -the [lesson template][swc-lesson-template] +We want it to be easy for authors to merge changes +made to the [lesson template][swc-lesson-template] into their lesson. If the lesson template contained all of the documentation in this example, then every time a merge was done, @@ -169,7 +182,7 @@ will avoid this problem. (Note that from Fall 2014 to Spring 2015 we tried using two branches in a single repository, one for the core files and one for the example. -Many contributors found it confusing; +Many contributors [found it confusing](https://github.com/swcarpentry/lesson-template/issues/118); we hope that separate repositories will be easier to keep straight.) ## Lesson Structure @@ -229,11 +242,15 @@ and ask for help there. ## Getting and Giving Help -We are committed to offering a pleasant setup experience for our learners and organizers. If you find bugs in our instructions, or would like to suggest improvements, -please [file an issue](https://github.com/swcarpentry/lesson-template/issues) -or [mail us](mailto:admin@software-carpentry.org). +please [file an issue in this repository](https://github.com/swcarpentry/lesson-example/issues); +if you find bugs in the template files themselves, +please [file an issue in the `lesson-template` repository](https://github.com/swcarpentry/lesson-template/issues). +You can also [mail us](mailto:admin@software-carpentry.org) with questions or problems. + +Please also [mail us](mailto:admin@software-carpentry.org) +whenever you create a new lesson and would like to advertise it on our web site. [swc]: http://software-carpentry.org [swc-lesson-template]: https://github.com/swcarpentry/lesson-template diff --git a/motivation.md b/motivation.md index 3ffcd0e..5b1a065 100644 --- a/motivation.md +++ b/motivation.md @@ -11,8 +11,8 @@ We make scientists and engineering more productive by teaching them basic comput ## The Problem - Surveyed 1972 scientists in 2008. -- “How do you use computers?” -- “How did you learn what you know?” +- "How do you use computers?" +- "How did you learn what you know?" ## The Problem @@ -25,7 +25,7 @@ We make scientists and engineering more productive by teaching them basic comput ## The Problem - No hard data on how *well* they do things. -- But anecdotal evidence suggests “not very”. +- But anecdotal evidence suggests "not very". ## Our Solution -- GitLab