diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000000000000000000000000000000000000..b5fd710e61c716aa0a345bdf2ab9ad23fb726002 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,81 @@ +## Background and Design + +There are a few things you need to know in order to understand why +this template is organized the way it is: + +1. Git uses the term *clone* to mean "a copy of a repository". + GitHub uses the term *fork* to mean, "a copy of a GitHub-hosted + repo that is also hosted on GitHub", and the term *clone* to mean + "a copy of a GitHub-hosted repo that's located on someone else's + machine". In both cases, the duplicate has a remote called + `origin` that points to the original repo; other remotes can be + added manually. + +2. A user on GitHub can only have one fork of a particular repo. + This is a problem for us because an author may be involved in + writing several lessons, each of which has its own website repo. + Those website repositories ought to be forks of this one, but + since GitHub doesn't allow that, we've had to find a workaround. + +3. If a repository has a branch called `gh-pages` (which stands for + "GitHub pages"), then GitHub uses the HTML and Markdown files in + that branch to create a website for the repository. If the + repository's URL is `http://github.com/darwin/finches`, the URL + for the website is `http://darwin.github.io/finches`. + +4. We use Markdown for writing pages because it's simple to learn, + and isn't tied to any specific language (the ReStructured Text + format popular in the Python world, for example, is a complete + unknown to R programmers). If authors want to use something else + to author their lessons (e.g., IPython Notebooks), it's up to them + to generate and commit Markdown formatted according to the rules + below. + + **Note:** we do *not* prescribe what tools instructors should use + when actually teaching. The IPython Notebook, Python IDEs like + Spyder, and the GOCLI (Good Ol' Command Line Interpreter) are all + equally welcome up on stage --- all we specify is the format of + the lesson notes. + +5. We use Pandoc to process pages instead of Jekyll (GitHub's default + conversion tool) because Pandoc supports a much richer dialect of + Markdown than Jekyll. Like Jekyll, Pandoc looks for a header at + the top of each page formatted like this: + + ~~~ + --- + variable: value + other_variable: other_value + --- + ...stuff in the page... + ~~~ + + and inserts the values of those variables into the page when + formatting this. Lesson authors will usually not have to worry + about this. + +6. Using Pandoc instead of Jekyll means that we have to compile our + Markdown into HTML on our own machines and commit it to the + `gh-pages` branch of the lesson's GitHub repository. In order to + keep our source files and generated files separate, we put our + source files in a sub-directory called `pages`, and compile them + "upward" into the root directory of the lesson's repository. + + **Note:** while it's usually considered bad practice to put + computer-generated files under version control, the HTML pages put + into the lesson's root directory by Pandoc *must* be committed to + version control in order for the lesson to be displayed properly + on GitHub. + +7. In order to display properly, our generated HTML pages need + artwork, CSS style files, and a few bits of Javascript. We could + load these from the web, but that would make offline authoring + difficult. Instead, each lesson's repository has a copy of these + files, and a way of updating them (and only them) on demand. + +One final note: we try not to put HTML inside Markdown because it's +ugly to read and write, and error-prone to process. Instead, we put +things that ought to be in `
` blocks, like the learning +objectives and challenge exercises, in blocks indented with `>`, and +do a bit of post-processing to attach the right CSS classes to these +blocks. diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000000000000000000000000000000000000..838ce90db414d4ceffb568df65abb5afb8c7ce49 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,39 @@ +## FAQ + +* *Where can I get help?* + + Mail us at [admin@software-carpentry.org](mailto:admin@software-carpentry.org), + or join our [discussion list](http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org) + and ask for help there. + +* *Where can I report problems or suggest improvements?* + + Please + [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 from scratch? 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. + +* *Why use Pandoc? Why not some other markup language and some other converter?* + + Because it supports a richer dialect of Markdown than Jekyll + (the converter that GitHub uses by default). + +* *What do the [labels](https://github.com/swcarpentry/lesson-template/issues?q=is%3Aopen+is%3Aissue) mean?* + + * `bug`: something is wrong in our tools or documentation + * `discussion`: marks issues used for conversations about specific problems and questions + * `duplicate`: marks an issue that was closed as redundant (include the number of the original issue in the closing comment) + * `enhancement`: asks for, or adds, a new feature or new information + * `filed-by-newcomer`: issue or pull request was filed by someone new to GitHub and/or this project + * `getting-started`: issue or pull request is suitable for someone new to GitHub and/or this project + * `help-wanted`: a question or request for assistance + * `wont-fix`: marks an issue that isn't going to be addressed + * `work-in-progress`: a pull request that is not yet ready for review + +## Debugging + +Please add notes about problems and solutions below. diff --git a/LAYOUT.md b/LAYOUT.md new file mode 100644 index 0000000000000000000000000000000000000000..5b87c14a9bfe0281f0f80c46189bad48bcd0a496 --- /dev/null +++ b/LAYOUT.md @@ -0,0 +1,335 @@ +# Lesson Layout + +Each lesson is stored in a directory laid out as described below. That +directory is a self-contained Git repository (i.e., there are no +submodules or clever tricks with symbolic links). + +1. `README.md`: initially a copy of this file. It should be + overwritten with short description of the lesson. + +2. `pages/`: a sub-directory containing the source of the lesson's + website. See "Pages" below. + +3. `code/`, `data/`, and `fig/`: sub-directories containing sample + code, data files, and figures. See "Code, Data, and Figures" + below. + +4. `css/`, `img/`, and `js/`: style sheets, artwork, and Javascript + used in the lesson's web site. See "Support Files" below. + +5. `_layouts/` and `_includes/`: page templates and inclusions. See + "Support Files" below. + +6. `tools/`: tools for managing lessons. See "Tools" below. + +# Code, Data, and Figures + +All of the software samples used in the lesson must go in a directory +called `code/`. Stand-alone data files must go in a directory called +`data/`. Groups of related data files must be put together in a +sub-directory of `data/` with a meaningful (short) name. Figures, +plots, and diagrams used in the lessons must go in a `fig/` directory. + +**Notes:** + +1. This mirrors the layout a scientist would use for actual work. + However, it may cause novice learners problems. If a program is + in `code/a.py`, and contains a reference to a data file + `../data/b.csv`, then if the user runs the program from the root + directory using `python code/a.py`, it will be unable to find the + data file (since the program's working directory will be the root + directory, not the `data` directory). + +2. We strongly prefer SVG for line drawings, since they are smaller, + scale better, and are easier to edit. Screenshots and other raster + images must be PNG or JPEG format. + +# Support Files + +Files used to display the lesson, such as artwork, CSS, and +Javascript, are stored in directories of their own. We keep website +artwork separate from graphics used in the lesson's to make it simple +to update the former automatically. Most authors should not need to +modify any of the support files themselves. + +The `_layouts/` directory holds the page templates used to translate +Markdown to HTML, while the `_includes/` directory holds snippets of +HTML that are used in several page layouts. These directories have +underscores at the start of their names to be consistent with Jekyll's +naming conventions, but the files they contain are for Pandoc. + +# Tools + +The `tools/` directory contains tools to help create and maintain +lessons: + +* `tools/check`: make sure that everything is formatted properly, and + print error messages identifying problems if it's not. + +# Pages + +The `pages/` directory holds the content of the lesson, and must +contain: + +1. `Makefile`: contains commands to check, preview, and update the + repository. Authors should not need to modify this file. + +2. `index.md`: the home page for the lesson. (See "Home Page" below.) + +3. `dd-slug.md`: the topics in the lesson. `dd` is a sequence number + such as `01`, `02`, etc., and `slug` is an abbreviated single-word + mnemonic for the topic. Thus, `03-filesys.md` is the third topic in + this lesson, and is about the filesystem. (Note that we use hyphens + rather than underscores in filenames.) See "Topics" below. + +4. `motivation.md`: slides for a short introductory presentation (three + minutes or less) explaining what the lesson is about and why people + would want to learn it. See "Introductory Slides" below. + +5. `reference.md`: a cheat sheet summarizing key terms and commands, + syntax, etc., that can be printed and given to learners. See + "Reference Guide" below. + +6. `discussion.md`: notes about more advanced ideas that would + distract from the main lesson, and pointers to where to go next. + See "Discussion Page" below. + +7. `instructors.md`: the instructor's guide for the lesson. See + "Instructor's Guide" below. + +Note that the lesson's title is repeated in several files. We could +put this in the Makefile, and insert it into pages when compiling, but +then authors would have to edit the Makefile (which we're trying to +avoid requiring). We could also put it in some sort of configuration +file, but again, we're trying to avoid those. + +## Home Page + +`index.md` must be structured as follows: + + --- + layout: lesson + title: Lesson Title + --- + Paragraph(s) of introductory material. + + > ## Prerequisites {.prereq} + > + > What learners need to know before tackling this lesson. + + ## Topics + + 1. [Topic Title 1](01-slug.html) + 2. [Topic Title 2](02-slug.html) + + ## Other Resources + + * [Motivation](motivation.html) + * [Reference Guide](reference.html) + * [Next Steps](discussion.html) + * [Instructor's Guide](instructors.html) + +**Notes:** + +1. The description of prerequisites is prose for human consumption, + not a machine-comprehensible list of dependencies. We may + supplement the former with the latter once we have more experience + with this lesson format and know what we actually want to do. + +2. Software installation and configuration instructions *aren't* in + the lesson, since they may be shared with other lessons. They will + be stored centrally on the Software Carpentry web site and linked + from the lessons that need them. + +## Topics + +Each topic page must be structured as follows: + + --- + layout: page + title: Lesson Title + subtitle: Topic Title + minutes: 10 + --- + > ## Learning Objectives {.objectives} + > + > * Learning objective 1 + > * Learning objective 2 + + Paragraphs of text --- possibly including **definitions** --- + mixed with: + + ~~~ {.python} + some code: + to be displayed + ~~~ + + and: + + ~~~ {.output} + output + from + program + ~~~ + + and: + + ~~~ {.error} + error reports from programs (if any) + ~~~ + + and possibly including some of these: + + > ## Callout Box {.callout} + > + > An aside of some kind. + + and one or more of these: + + > ## Challenge Title {.challenge} + > + > Description of a single challenge. + > There may be several challenges. + +**Notes:** + +1. The "expected time" heading is called minutes to encourage people + to create topics that are short (10-15 minutes at most). + +2. There are no sub-headings inside a topic other than the ones + shown. (If a topic needs sub-headings, it should be broken into + two or more topics.) + +3. Every challenge should relate explicitly back to a learning + objective. + +4. Definitions of terms are marked in **bold** (like `**this**`). + +## Motivational Slides + +Every lesson must include a short slide deck 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: + + --- + layout: slides + title: Why Make? + --- +
+ ## Why This Topic? +
+ +
+ ## Some Other Point +
+ + +**Notes:** + +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. + +2. 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/). + +## Reference Guide + +The reference guide 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). + +The last section of the reference guide must be a glossary laid out as +a definition list: + + --- + layout: page + title: Lesson Title + subtitle: Reference + --- + ...commands and examples... + + ## Glossary + + Key Word 1 + : Definition of first term + + Key Word 2 + : Definition of second term + +## Discussion Page + +The discussion page + + --- + layout: page + title: Lesson Title + subtitle: Discussion + --- + * First point of general discussion. + + This may span several paragraphs. + + * Second point of general discussion. + +## 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: + + --- + layout: page + title: Lesson Title + subtitle: Instructor's Guide + --- + ## Legend + + One or more paragraphs laying out the lesson's legend (i.e., the story + behind its running example). + + ## Overall + + * Point + + * Point + + ## [Topic Title 1](01-slug.html) + + * Point + + * Point + + 1. Discussion of first challenge. + + 2. Discussion of second challenge. + + ## [Topic Title 2](02-slug.html) + + * Point + + * Point + + 1. Discussion of first challenge. + + 2. Discussion of second challenge. + +**Notes:** + +1. The topic headings must match the topic titles. (Yes, we could + define these as variables in a configuration file and refer to those + variables everywhere, but in this case, repetition will be a lot + easier to read, and our validator can check that the titles line + up.) + +2. The points can be anything: specific ways to introduce ideas, common + mistakes learners make and how to get out of them, or anything else. + +3. Full solutions to the challenges do not have to be presented, but + every challenge should be discussed, and that discussion should + mention how long it typically takes to do. (Those estimates do + not go in the challenge itself, since they can increase learners' + stress levels.) diff --git a/README.md b/README.md index 9dcef10c6b71b2f4b4fd25eaf6f0c0815b73f90f..4999b5b6b0c4b14f748f5c8c163ab0352c1a2f40 100644 --- a/README.md +++ b/README.md @@ -149,420 +149,24 @@ Authors may retain copyright on their lessons, but we ask that all lessons be published under the Creative Commons - Attribution (CC-BY) license, or put in the public domain (CC-0), to permit remixing. -## Background - -There are a few things you need to know in order to understand why -this template is organized the way it is: - -1. Git uses the term *clone* to mean "a copy of a repository". - GitHub uses the term *fork* to mean, "a copy of a GitHub-hosted - repo that is also hosted on GitHub", and the term *clone* to mean - "a copy of a GitHub-hosted repo that's located on someone else's - machine". In both cases, the duplicate has a remote called - `origin` that points to the original repo; other remotes can be - added manually. - -2. A user on GitHub can only have one fork of a particular repo. - This is a problem for us because an author may be involved in - writing several lessons, each of which has its own website repo. - Those website repositories ought to be forks of this one, but - since GitHub doesn't allow that, we've had to find a workaround. - -3. If a repository has a branch called `gh-pages` (which stands for - "GitHub pages"), then GitHub uses the HTML and Markdown files in - that branch to create a website for the repository. If the - repository's URL is `http://github.com/darwin/finches`, the URL - for the website is `http://darwin.github.io/finches`. - -4. We use Markdown for writing pages because it's simple to learn, - and isn't tied to any specific language (the ReStructured Text - format popular in the Python world, for example, is a complete - unknown to R programmers). If authors want to use something else - to author their lessons (e.g., IPython Notebooks), it's up to them - to generate and commit Markdown formatted according to the rules - below. - - **Note:** we do *not* prescribe what tools instructors should use - when actually teaching. The IPython Notebook, Python IDEs like - Spyder, and the GOCLI (Good Ol' Command Line Interpreter) are all - equally welcome up on stage --- all we specify is the format of - the lesson notes. - -5. We use Pandoc to process pages instead of Jekyll (GitHub's default - conversion tool) because Pandoc supports a much richer dialect of - Markdown than Jekyll. Like Jekyll, Pandoc looks for a header at - the top of each page formatted like this: +## For More Information - ~~~ - --- - variable: value - other_variable: other_value - --- - ...stuff in the page... - ~~~ - - and inserts the values of those variables into the page when - formatting this. Lesson authors will usually not have to worry - about this. - -6. Using Pandoc instead of Jekyll means that we have to compile our - Markdown into HTML on our own machines and commit it to the - `gh-pages` branch of the lesson's GitHub repository. In order to - keep our source files and generated files separate, we put our - source files in a sub-directory called `pages`, and compile them - "upward" into the root directory of the lesson's repository. - - **Note:** while it's usually considered bad practice to put - computer-generated files under version control, the HTML pages put - into the lesson's root directory by Pandoc *must* be committed to - version control in order for the lesson to be displayed properly - on GitHub. - -7. In order to display properly, our generated HTML pages need - artwork, CSS style files, and a few bits of Javascript. We could - load these from the web, but that would make offline authoring - difficult. Instead, each lesson's repository has a copy of these - files, and a way of updating them (and only them) on demand. - -One final note: we try not to put HTML inside Markdown because it's -ugly to read and write, and error-prone to process. Instead, we put -things that ought to be in `
` blocks, like the learning -objectives and challenge exercises, in blocks indented with `>`, and -do a bit of post-processing to attach the right CSS classes to these -blocks. - -## Overall Layout - -Each lesson is stored in a directory laid out as described below. That -directory is a self-contained Git repository (i.e., there are no -submodules or clever tricks with symbolic links). - -1. `README.md`: initially a copy of this file. It should be - overwritten with short description of the lesson. - -2. `pages/`: a sub-directory containing the source of the lesson's - website. See "Pages" below. - -3. `code/`, `data/`, and `fig/`: sub-directories containing sample - code, data files, and figures. See "Code, Data, and Figures" - below. - -4. `css/`, `img/`, and `js/`: style sheets, artwork, and Javascript - used in the lesson's web site. See "Support Files" below. - -5. `_layouts/` and `_includes/`: page templates and inclusions. See - "Support Files" below. - -6. `tools/`: tools for managing lessons. See "Tools" below. - -## Code, Data, and Figures - -All of the software samples used in the lesson must go in a directory -called `code/`. Stand-alone data files must go in a directory called -`data/`. Groups of related data files must be put together in a -sub-directory of `data/` with a meaningful (short) name. Figures, -plots, and diagrams used in the lessons must go in a `fig/` directory. - -**Notes:** - -1. This mirrors the layout a scientist would use for actual work. - However, it may cause novice learners problems. If a program is - in `code/a.py`, and contains a reference to a data file - `../data/b.csv`, then if the user runs the program from the root - directory using `python code/a.py`, it will be unable to find the - data file (since the program's working directory will be the root - directory, not the `data` directory). - -2. We strongly prefer SVG for line drawings, since they are smaller, - scale better, and are easier to edit. Screenshots and other raster - images must be PNG or JPEG format. - -## Support Files - -Files used to display the lesson, such as artwork, CSS, and -Javascript, are stored in directories of their own. We keep website -artwork separate from graphics used in the lesson's to make it simple -to update the former automatically. Most authors should not need to -modify any of the support files themselves. - -The `_layouts/` directory holds the page templates used to translate -Markdown to HTML, while the `_includes/` directory holds snippets of -HTML that are used in several page layouts. These directories have -underscores at the start of their names to be consistent with Jekyll's -naming conventions, but the files they contain are for Pandoc. - -## Tools - -The `tools/` directory contains tools to help create and maintain -lessons: - -* `tools/check`: make sure that everything is formatted properly, and - print error messages identifying problems if it's not. - -## Pages - -The `pages/` directory holds the content of the lesson, and must -contain: - -1. `Makefile`: contains commands to check, preview, and update the - repository. Authors should not need to modify this file. - -2. `index.md`: the home page for the lesson. (See "Home Page" below.) - -3. `dd-slug.md`: the topics in the lesson. `dd` is a sequence number - such as `01`, `02`, etc., and `slug` is an abbreviated single-word - mnemonic for the topic. Thus, `03-filesys.md` is the third topic in - this lesson, and is about the filesystem. (Note that we use hyphens - rather than underscores in filenames.) See "Topics" below. - -4. `motivation.md`: slides for a short introductory presentation (three - minutes or less) explaining what the lesson is about and why people - would want to learn it. See "Introductory Slides" below. - -5. `reference.md`: a cheat sheet summarizing key terms and commands, - syntax, etc., that can be printed and given to learners. See - "Reference Guide" below. - -6. `discussion.md`: notes about more advanced ideas that would - distract from the main lesson, and pointers to where to go next. - See "Discussion Page" below. - -7. `instructors.md`: the instructor's guide for the lesson. See - "Instructor's Guide" below. - -Note that the lesson's title is repeated in several files. We could -put this in the Makefile, and insert it into pages when compiling, but -then authors would have to edit the Makefile (which we're trying to -avoid requiring). We could also put it in some sort of configuration -file, but again, we're trying to avoid those. - -### Home Page - -`index.md` must be structured as follows: - - --- - layout: lesson - title: Lesson Title - --- - Paragraph(s) of introductory material. - - > ## Prerequisites {.prereq} - > - > What learners need to know before tackling this lesson. - - ## Topics - - 1. [Topic Title 1](01-slug.html) - 2. [Topic Title 2](02-slug.html) - - ## Other Resources - - * [Motivation](motivation.html) - * [Reference Guide](reference.html) - * [Next Steps](discussion.html) - * [Instructor's Guide](instructors.html) - -**Notes:** - -1. The description of prerequisites is prose for human consumption, - not a machine-comprehensible list of dependencies. We may - supplement the former with the latter once we have more experience - with this lesson format and know what we actually want to do. - -2. Software installation and configuration instructions *aren't* in - the lesson, since they may be shared with other lessons. They will - be stored centrally on the Software Carpentry web site and linked - from the lessons that need them. - -### Topics - -Each topic page must be structured as follows: - - --- - layout: page - title: Lesson Title - subtitle: Topic Title - minutes: 10 - --- - > ## Learning Objectives {.objectives} - > - > * Learning objective 1 - > * Learning objective 2 - - Paragraphs of text --- possibly including **definitions** --- - mixed with: - - ~~~ {.python} - some code: - to be displayed - ~~~ - - and: - - ~~~ {.output} - output - from - program - ~~~ - - and: - - ~~~ {.error} - error reports from programs (if any) - ~~~ - - and possibly including some of these: - - > ## Callout Box {.callout} - > - > An aside of some kind. - - and one or more of these: - - > ## Challenge Title {.challenge} - > - > Description of a single challenge. - > There may be several challenges. - -**Notes:** - -1. The "expected time" heading is called minutes to encourage people - to create topics that are short (10-15 minutes at most). - -2. There are no sub-headings inside a topic other than the ones - shown. (If a topic needs sub-headings, it should be broken into - two or more topics.) - -3. Every challenge should relate explicitly back to a learning - objective. - -4. Definitions of terms are marked in **bold** (like `**this**`). - -### Motivational Slides - -Every lesson must include a short slide deck 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: - - --- - layout: slides - title: Why Make? - --- -
- ## Why This Topic? -
- -
- ## Some Other Point -
- - -**Notes:** - -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. - -2. 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/). - -### Reference Guide - -The reference guide 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). - -The last section of the reference guide must be a glossary laid out as -a definition list: - - --- - layout: page - title: Lesson Title - subtitle: Reference - --- - ...commands and examples... - - ## Glossary - - Key Word 1 - : Definition of first term - - Key Word 2 - : Definition of second term - -### Discussion Page - -The discussion page - - --- - layout: page - title: Lesson Title - subtitle: Discussion - --- - * First point of general discussion. - - This may span several paragraphs. - - * Second point of general discussion. - -### 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: - - --- - layout: page - title: Lesson Title - subtitle: Instructor's Guide - --- - ## Legend - - One or more paragraphs laying out the lesson's legend (i.e., the story - behind its running example). - - ## Overall - - * Point - - * Point - - ## [Topic Title 1](01-slug.html) - - * Point - - * Point - - 1. Discussion of first challenge. - - 2. Discussion of second challenge. - - ## [Topic Title 2](02-slug.html) - - * Point - - * Point - - 1. Discussion of first challenge. +Please see the following for more information on: - 2. Discussion of second challenge. +* [layout out your lesson](LAYOUT.md) +* [background and design](DESIGN.md) +* [FAQ](FAQ.md) -**Notes:** +## Getting Help -1. The topic headings must match the topic titles. (Yes, we could - define these as variables in a configuration file and refer to those - variables everywhere, but in this case, repetition will be a lot - easier to read, and our validator can check that the titles line - up.) +Mail us at [admin@software-carpentry.org](mailto:admin@software-carpentry.org), +or join our [discussion list](http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org) +and ask for help there. -2. The points can be anything: specific ways to introduce ideas, common - mistakes learners make and how to get out of them, or anything else. +## Giving Help -3. Full solutions to the challenges do not have to be presented, but - every challenge should be discussed, and that discussion should - mention how long it typically takes to do. (Those estimates do - not go in the challenge itself, since they can increase learners' - stress levels.) +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?q=is%3Aopen+is%3Aissue) +or [mail us](mailto:admin@software-carpentry.org).