We've developed a lot of collective wisdom as instructors over the last several years as we've taught boot camps around the world. This issue will serve as an initial collection point for tips that will end up in a centrally collected place on the website.

Before you contribute, a few guidelines:

I'd prefer to format the contribution page in such a way that we provide a link to the instructor who initially suggested the tip. Please format your name with a URL that you would like if you provide a tip (e.g. from Aron Ahmadia. I can't promise that we'll credit you, but there's a good chance it will happen if you provide something particularly novel or effective.

Try to add a couple keywords that will help us categorize your tip. Please re-use a keyword if it's already active and close. Otherwise, feel free to add your own! Here are a few suggestions.

• planning
• assessment
• technical troubleshooting
• breaking the ice
• establishing credibility
• one-on-one help
• examples and exercises
• wrapping up
• following up

Please keep discussion in this thread. I'll start up a separate announcement of this thread on discuss, but we're going to try this discussion as a GitHub issue and see how it goes.

Please check if your tip already exists either in the thread or in one of our other pages. Feel free to throw in a "me too", or a link to the tip if you have an improvement or modification to the way the tip is currently stated. Be polite!

Here are the places I'm aware of tips existing on our website. If you find another location where tips are posted, bonus points for you and I'll fix this top-level post to reflect that.

• http://software-carpentry.org/bootcamps/operations.html
• http://software-carpentry.org/bootcamps/checklists/instructors.html
• http://software-carpentry.org/bootcamps/checklists/lead_instructor.html
• http://software-carpentry.org/bootcamps/checklists/helpers.html

lessons/swc-python/python-6-testing.ipynb needs a callout box pointing people at Nose, and giving some examples - Ears is just a toy for use in the notebook.

Thanks to a recent G+ post by Anthony Scopatz, Ninja IDE is now on my radar.

http://ninja-ide.org/

This looks like it could be a serious contender in the "friendly cross-platform freely available code editor with Shell/Python support" camp that would make it center-line for Software Carpentry installs. We're currently defaulting to nano, but I'm hoping that we can start considering a heavier cross-platform IDE. Other contenders in this category are Spyder and Eclipse.

I just walked through an installation on OS X (I've got homebrew, so installing sip and pyqt is a matter of a fast Internet connection and a bit of patience).

A couple salient points:

Pros

• Open License (GPLv3) [1]
• Openly Developed on GitHub [2]
• Good Python support/integration
• Windows and Linux installers
• Syntax, completion, string highlighting

Cons

• Seemingly no IDE integration with Bash
• Heavy PyQt dependences, making installation from source non-trivial for all but the most brave.
• No OS X binary installer [3]
• Look-and-feel is a bit clunky

It's not clear whether the GPLv3 License allows redistribution with meta-packages such as Anaconda or Canopy.

Update: Both @scopatz and @r-gaia-cs have pointed to clear examples where this is allowed.

It would be nice to have a cross-platform editor that we generally recommend and that is a little more serious than nano (sorry Ethan!).

[1] http://ninja-ide.org/about/
[2] https://github.com/ninja-ide/ninja-ide
[3] http://ninja-ide.org/downloads/

1. In swc-shell, some images are broken(Like Figure 4), I can send a PR later.
2. But it seems some images are lost? Like Figure 9: The Nano Editor. Can not find in the bc repo. But I find them at guide repo. What can I do?

This issue is tracking the image reorganization efforts in bc. Please centralize discussion here.

Originally, via @HaveF, @gvwilson and @r-gaia-cs, we found some missing images and restored them to the bc repository but did not quite land them in the proper location. #68

Hi,
I try to reproduce the example below about spaces in names from the shell lesson:

$ for filename in *.dat; do echo $filename; done
basilisk.dat
red
dragon.dat
unicorn.dat

But I got a different behavior as show below:

$ bash --version
GNU bash, version 4.2.45(2)-release (x86_64-unknown-linux-gnu)
Copyright (C) 2011 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

This is free software; you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
# build files
$ touch -f "basilisk.dat"
$ touch -f "red dragon.dat"
$ touch -f "unicorn.dat"
# First loop from lesson
$ for f in *.dat; do echo $f; done
basilisk.dat
red dragon.dat
unicorn.dat
# Second loop using shell expansion
$ for f in $(ls *.dat); do echo $f; done
basilisk.dat
red
dragon.dat
unicorn.dat

Note that when using for f in *.dat; do echo $f; done the name of the file red dragon.dat are not split (in the lesson it is).

I also test it with GNU bash 4.2.24 and get the same output. I can write a PR for this in the weekend but want to know about the behavior of others shells.

Thanks.

Can the css be improved to the 'box' class won't overflow the window width?

We agreed the following during discussion of #120:

• Each Python lesson is stored in a single notebook (but the novice and intermediate lessons are in separate notebooks).
• Each notebook contains long-form prose, notes for learners, and notes for instructors as well as code.
• Cells in these notebook are tagged using https://github.com/jdfreder/notebook_cherry_picker.
• We run these notebooks through nbconvert to construct the notebooks that will be given to learners as a starting point in class, used by the instructor in class, read by the instructor before class to prepare, etc.

I expect a master notebook to include some or all of:

• a main title and section subtitles;
• a point-form summary of lesson objectives;
• a point-form summary of key points;
• an introductory motivating story;
• call-out boxes (which are usually formatted differently from regular text);
• challenges (i.e., questions or exercises);
• complete, functional pieces of code;
• skeletal (non-functional) code for learners to use as a starting point for challenges;
• diagrams (i.e., file images included in the notebook ratherthan plots generated by the notebook's code);
• point-form notes for learners;
• point-form notes for instructors (e.g., teaching tips);
• prose (i.e., long-form material) for learners; and
• prose for instructors.

I therefore propose this vocabulary for cell tags:

• instructor: material intended only for the instructors
• learner: material given to learners in class
• challenge: a question or exercise
• solution: a solution to a question or exercise
• objectives: lesson objectives
• summary: lesson summary
• box: for call-out boxes

Notes:

1. A single cell can have multiple tags.
2. A notebook will only have one set of objectives and one summary. (if it's large enough to need objectives and summaries for each section, it should be split into multiple notebooks.)
3. Objectives and summaries are just more Markdown, but we want to be able to extract them from notebooks to create the bootcamp's syllabus and handouts.
4. We expect that objectives and summaries will be point-form, but don't require this.
5. There is currently no way to group cells, e.g., to indicate that this discussion and that code are part of the same challenge question or call-out box. We won't worry about this until the notebook acquires cell grouping.
6. There is currently no way to mark a cell as "code not to be executed" (for skeletal starting points for challenge questions). The closest we can get is to write the code as Markdown, and have learners change the cell type to code when they start working with it.
7. I usually put the tags that include diagrams in cells of their own, rather than in the middle of text, but most people don't, so I haven't proposed a separate cell tag for figures.

Finally, definitions of new terms should be written like this:

The web server processes each [HTTP request](../gloss.html#http-request) separately.

I.e., the first use of the term is a hyperlink to the file gloss.html in the root directory of the repository,
and each entry in the glossary has a hyphenated lower-case label.
Bibliographic references are written similarly, though they point to a different file:

Our guidelines for laying out small projects are drawn from [Noble 1999](../biblio.html#noble-1999).

[Update] Nov 2, 2013 - We are currently not accepting domain-specific material into the bc repository. Please see @gvwilson's post on Scope and this guiding statement:

Domain-specific tools for machine learning and computational fluid dynamics aren't built into LAPACK or NumPy: they're stored in separate repositories and released in their own packages. Similarly, domain-specific lessons don't belong in Software Carpentry. Instead, they should build on our lessons, just as computer vision libraries build on matrix and image libraries. Our examples should be drawn from biology, physics, economics, and similar disciplines in order to appeal to our audience, but everything we include must be accessible to anyone who's done freshman science.

Original issue for context

Per #110, I'd like to ensure that we have a consistent strategy with regards to adding domain-specific material to the bc repository.

Just as we have a consistent set of core SWC and THW lessons with some additional reproducibility and bioinformatics material, I would really like to have some domain-specific content in the bc repository that lives alongside the core SWC materials. There are strong advantages to introducing students to material that is flavored towards their own experiences and needs, and I want bc to be a place where we can collect suitably general, well-edited, lessons for explaining this.

I don't want to discuss this in #110, which is a specific PR, but I will hold off on merging anything in until we've agreed on this.

We need a summary page summarizing experiences/pros and cons of various approaches to running things on Windows.

lessons/guide-setdict/_.ipynb needs to be proofread. Remember to look in includes/guide-setdict//challenges/*.html for challenge exercises.

Construct a lesson for novices on the Unix shell in bash/novice.

Construct lesson on Python for intermediates in r/intermediate.

Is there any point keeping the 'master' branch in this repo?

I followed the README.md, but stumble at

make check

because some issues are related with Windows and character encoding.

After a quick search, I solved these problems, but do I need to add these tips to README.md?

Construct a lesson on Python for novices in novice/python.

Should we change the default behavior of make so that

$ make

build the _site directory and

$ make help

give others commands?

lessons/swc-python/python-6-testing.ipynb needs a forward reference to the lesson that grows a larger program step-by-step as an introduction to refactoring (the term is used in lessons/swc-python/python-6-testing.ipynb, but not really illustrated).

Construct lesson on SQL for intermediates in sql/intermediate.

This issue is for discussion of issues around structure and metadata, including:

• What metadata should we put in lessons to make material findable?
• Where should that live? In the lesson materials, in README files, ...?
• More generally, what structure should lessons in various formats have? What files should lesson directories include, where should data files go, what title/sub-title conventions should we use, ...?

See also: #119 (tooling)

Hello all,

I and Joshua want to know what you think about add the shell parameter expansion for search and replace in the shell lesson (probably in the loop section).

The shell parameter expansion for search and replace is given by ${PARAMETER/PATTERN/STRING}. A little example:

$ SOMEVAR='shell'
$ echo $SOMEVAR
shell
$ echo ${SOMEVAR/shell/python}
python

Why we want to add it? Because it make life easy as in correcting some typo in the name of some files:

$ for f in $(ls | grep typpo); do mv $f ${f/typpo/typo}; done

As @gvwilson mentioned, some figures are not finished yet.

1. Except those unfinished figures, I suspect there are lots of figures lost in some where(like #67), and not put in this repo. Because some figures name are well defined, or @gvwilson already has drafts in his head. Here is a very short list.

   _includes/guide-db/select/lesson.html:      <img src="db/firefox_output.png" alt="Firefox SQLite Manager Output" />
   _includes/guide-db/select/lesson.html:      <img src="db/notebook_output.png" alt="IPython Notebook Database Extension Output" />
   _includes/guide-db/sort/lesson.html:    <img src="db/pipeline_sort_distinct.png" alt="Four-Stage Query Processing Pipeline" />
   _includes/guide-invperc/alias/lesson.html:    <img src="dev/alias_bug.png" alt="Aliasing Bug" />
   _includes/guide-invperc/assembly/lesson.html:    <img src="dev/structure_a.png" alt="Program Structure (A)" />
   _includes/guide-invperc/assembly/lesson.html:<pre src="src/dev/invperc_initial.py">
   _includes/guide-invperc/assembly/lesson.html:    <img src="dev/structure_b.png" alt="Program Structure (B)" />
   _includes/guide-invperc/assembly/lesson.html:    <img src="dev/structure_c.png" alt="Program Structure (C)" />
   _includes/guide-invperc/assembly/lesson.html:  <img src="dev/structure_d.png" alt="Program Structure (D)" />
   _includes/guide-invperc/bugs/lesson.html:    <img src="dev/debugger.png" alt="Debugging the Grid" />
   _includes/guide-pyblocks/basic/lesson.html:    <img src="pymedia/ipython_welcome.png" alt="IPython Notebook Startup Screen" />
   _includes/guide-pyblocks/basic/lesson.html:    <img src="pymedia/empty_notebook.png" alt="An Empty Notebook" />
   _includes/guide-pyblocks/basic/lesson.html:    <img src="pymedia/first_computation.png" alt="Our First Computation" />
   _includes/guide-pyblocks/basic/lesson.html:    <img src="pymedia/architecture.png" alt="The Architecture of the IPython Notebook" />
   _includes/guide-pyblocks/basic/lesson.html:    <img src="pymedia/first_variable.png" alt="Our First Variable" />
   _includes/guide-pyblocks/basic/lesson.html:    <img src="pymedia/assign_new_value.png" alt="Assigning a New Value" />
   

2. About the unfinished figures, maybe it's hard to do and very time-comsuming. Who has the idea to handle this easily? Maybe it's too heavy to put all these figures on the @gvwilson 's shoulder.

Some more archaeology along the lines of (#79, #102, #89, #114). I'm about halfway through cherry-picking interesting commits out of:

$ git log --graph --topo-order --oneline --stat=160 --all | grep -i '\*\|testing' | grep -1i --color=always testing | less

I've posted my results so far in git://tremily.us/swc-testing-nose.git (http://git.tremily.us/?p=swc-testing-nose.git), with 10 occasionally-related lines of development ;).

$ git branch -a --list 'origin/*'
  remotes/origin/HEAD -> origin/test-thw-king
  remotes/origin/test-abostroem
  remotes/origin/test-ctb
  remotes/origin/test-ctb-2
  remotes/origin/test-howe
  remotes/origin/test-jackson
  remotes/origin/test-kitzes
  remotes/origin/test-thw-bray
  remotes/origin/test-thw-gidden
  remotes/origin/test-thw-king
  remotes/origin/test-thw-konrad

I've been trying to keep track of any testing content that's not in a binary file format (e.g. ODT, PPT, …), and I haven't made it up to https://github.com/swcarpentry/bc/blob/gh-pages/lessons/swc-python/python-06-testing.ipynb yet. Branch naming is somewhat arbitrary, usually using the first, last, or most prolific author in the branch, as the mood strikes me ;).

Automatically Generated PR Previews and Diffs [Updated 20 January 2014]

I'm experimenting with a script to generate HTML diffs from PRs. I think it should be easy to use this to verify IPython Notebook previews as well. I'm using this htmldiff script I found on the web:

https://github.com/cygri/htmldiff

If this is useful, we can discuss finding a permanent home for it somewhere in bc or site.

Here's what I've got so far:

Automated Diffs

Dependencies

htmldiff - slow, but works well out of the box
hub - soft, there are ways to access PRs without hub, but this is convenient
lftp - soft, needed if uploading to http://dev.ahmadia.net/swcarpentry
lsdiff from patchutils - soft, there are other ways to determine which files in a set of directories are different, but this is convenient

# script parameters
pr=211
user=swcarpentry-dev,ignore
host=sftp://ahmadia.net
hostdir=/users/home/aron/domains/dev.ahmadia.net/web/public/swcarpentry/bc
site=http://dev.ahmadia.net/swcarpentry/bc
merge_branch=master

# merge into $merge_branch so we can do a clean comparison
git fetch origin
hub checkout https://github.com/swcarpentry/bc/pull/$pr
git merge origin/$merge_branch -m "review, this commit should *not* end up in $merge_branch"
changed_sources=$(git diff --name-only $merge_branch)
pr_branch=$(git symbolic-ref --short HEAD)

# build suggested new version
make clean
make check
mv -f _site _site_${pr}

# build original version
git checkout origin/$merge_branch
make clean
make check

# create HTML diffs of modified files
changed_site_files=$(diff -ru _site_${pr} _site | lsdiff --strip=1)

for file in ${changed_site_files}
do
  htmldiff _site/$file _site_${pr}/$file >| _site_${pr}/${file/.html/_diff.html}
  echo _site_${pr}/${file/.html/_diff.html}
done

# upload
lftp -u $user -e "mirror -R _site_${pr} $hostdir/pull/$pr/preview; bye" $host

echo "PASTE THE FOLLOWING CONTENT INTO ISSUE TRACKER"
echo "=============================================="
echo "Preview the PR at: $site/pull/$pr"
echo "Proposed modifications:"
for file in ${changed_site_files}
do
  echo "  $site/pull/$pr/preview/${file/.html/_diff.html}
done
echo "New versions of modified files:"
do
  echo "  $site/pull/$pr/preview/${file}
done

sample outputs

http://aron.ahmadia.net/bc/pull/76/preview/lessons/swc-shell/tutorial.html
http://aron.ahmadia.net/bc/pull/76/preview/lessons/swc-shell/tutorial_diff.html

Construct a lesson on R for novices in r/novice.

Construct a lesson on SQL for novices in sql/novice.

We need to decide how to incorporate RMarkdown files and their conversion to html into the bc repo workflow (this issue inspired by @jduckles recent PR). The best solution would be one where only the RMarkdown file is committed to the repo and then is automatically converted to html when building the site with jekyll. Here is a link to one solution for accomplishing this. It involves adding an extra R file that to "knit" the files when rendering the website. My main concern is that this will slow down the build process if each time we have to run all of the R lessons in the repo. Thoughts?

Construct a lesson on Git for novices in git/novice.

While reviewing #90, I realized today that when we merged in the THW notebooks, we neglected to remove the now-deprecated Markdown files behind us.

For the shell content, we decided to explicitly leave the Markdown files in, because there is debate as to whether the Python Notebook is the most appropriate medium for teaching Bash or Git. Additionally, the SciPy material has not been converted over yet. However, this still leaves the following probably duplicates (I'm explicitly including the notebook files to make it obvious where the material is duplicated).

I'll go through these carefully to make sure I'm not deleting any non-duplicated material, but if for some reason you'd like the Markdown version of these files to stick around in the repository, this is the issue to speak up in!

Documentation

lessons/thw-documentation/close_line.md
lessons/thw-documentation/tutorial.ipynb
lessons/thw-documentation/tutorial.md

Matplotlib

lessons/thw-matplotlib/matplotlib-instructor.ipynb
lessons/thw-matplotlib/matplotlib-learner.ipynb
lessons/thw-matplotlib/tutorial.md

NumPy

lessons/thw-numpy/long_exercise.md
lessons/thw-numpy/numpy.ipynb
lessons/thw-numpy/tutorial.md

Python Debugging

lessons/thw-python-debugging/tutorial.ipynb
lessons/thw-python-debugging/tutorial.md

Testing

lessons/thw-testing/exercises.ipynb
lessons/thw-testing/exercises.md
lessons/thw-testing/testing-orig.md
lessons/thw-testing/tutorial.ipynb
lessons/thw-testing/tutorial.md
``

While taking another look at #93 I found the string '@@0@@' in some of the cells of shell-filedir-instructor.ipynb (see picture below).

Any one can give more information about it?

Material imported from the instructor's guide is poorly formatted right now; need better CSS for this.

The current protocol is for instructors create a new repo under their own accounts, then clone contents of the bc repo, and push to their own GitHub account. The problem with this approach is that it creates a fairly large repo (32.5 mb with no additional content from the instructor) with a ton of material that may never be taught at a particular bootcamp. Having all the students clone on what invariable turns out to be a slow connection becomes a bear.

I've experienced this twice that I was forced to quickly throw content elsewhere on the web (e.g. data files to work on for an exercise) on my personal page and have then curl that down.

I understand that this approach helps maintain the connections to the original bootcamp repo and (at least theoretically) make it easy to contribute content back, it doesn't work so well in practice.

Since Python 2.7 / 3.2, the built-in unittest module supports:

$ python -m unittest discover

This means that you don't have to collect your TestCases in suites anymore, which was my main reason for preferring nose over Python's built-in framework. I think we should transition our testing documentation to use the standard library. I don't expect this will be difficult, because it hasn't been for any of my personal projects. However, I haven't looked over the SWC testing lessons in a few months, so this may be a more intrusive change than I expect.

Thoughts?

This can be done in the repo settings and will help people new to gh-pages find the content

DISCLAIMER: I don't want to start a flame war.

Related with: #71 and #105.

I know that lots of Python packages are incompatible with Python3 and maybe never will be but lots of them already are (e.g. Numpy, Scipy, matplotlib, IPython, ...).

What about the Python lessons start using only Python3 print syntax?

Short version of why using Python3 print syntax

$ python2
Python 2.7.5 (default, Sep  6 2013, 09:55:21) 
[GCC 4.8.1 20130725 (prerelease)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> print 'foo'
foo
>>> print('foo')
foo
>>> quit()
$ python3
Python 3.3.2 (default, Sep  6 2013, 09:30:10) 
[GCC 4.8.1 20130725 (prerelease)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> print 'foo'
  File "<stdin>", line 1
    print 'foo'
              ^
SyntaxError: invalid syntax
>>> print('foo')
foo
>>> quit()

Long version of why using Python3 print syntax

Since Software Carpentry are teaching scientists how to better programming I think that keep using features that will be deprecated in "short" time instead of another that are back compatible isn't the way to show how to improve your programming skills.

We've recently received a PR for a concept map: #94

Some discussion has come up about the best way to generate and store these images. Rather than crowding #94, let's try and move the issue here, specifically addressing:

• What formats are acceptable for concept maps?
• What's our threshold for accepting them into the repository?

I think "bootcamp" is preferred according to the FAQ, however I see a few uses of "boot camp" in the template

@amyrbrown and others - any editorial guidance here?

8 October Update: We prefer bootcamp, note any spotted "boot camps" in the wild to this issue.

What is a tutorial on reproducible workflows https://github.com/swcarpentry/bc/blob/gh-pages/lessons/misc-biopython/reproducible_workflow.md doing inside the bio-python folder?

Rev ecdebf9 added a command-line build bug: lessons/python-debugging/tutorial.md generates the errors shown below from make check. There isn't a line number to help track it down in the source file (tutorial.md is the only new file, so presumably it's in that), and running Maruku standalone produces even more errors. Just to be irritating, the page displays fine on GitHub, even though it refuses to build on the command line.

/Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_span_better.rb:528:in `read_inline_code': undefined method `[]' for nil:NilClass (NoMethodError)
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_span_better.rb:89:in `read_span'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_span_better.rb:46:in `parse_span_better'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_span_better.rb:36:in `parse_lines_as_span'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_block.rb:275:in `read_paragraph'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_block.rb:158:in `read_text_material'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_block.rb:69:in `parse_blocks'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_block.rb:41:in `parse_text_as_markdown'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/input/parse_doc.rb:55:in `parse_doc'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/maruku-0.6.1/lib/maruku/maruku.rb:30:in `initialize'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/converters/markdown/maruku_parser.rb:44:in `new'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/converters/markdown/maruku_parser.rb:44:in `convert'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/converters/markdown.rb:39:in `convert'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/convertible.rb:50:in `transform'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/convertible.rb:128:in `do_layout'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/page.rb:111:in `render'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/site.rb:233:in `block in render'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/site.rb:231:in `each'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/site.rb:231:in `render'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/site.rb:44:in `process'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/command.rb:18:in `process_site'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/commands/build.rb:23:in `build'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/lib/jekyll/commands/build.rb:7:in `process'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/jekyll-1.0.3/bin/jekyll:61:in `block (2 levels) in <top (required)>'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/commander-4.1.3/lib/commander/command.rb:180:in `call'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/commander-4.1.3/lib/commander/command.rb:180:in `call'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/commander-4.1.3/lib/commander/command.rb:155:in `run'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/commander-4.1.3/lib/commander/runner.rb:402:in `run_active_command'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/commander-4.1.3/lib/commander/runner.rb:78:in `run!'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/commander-4.1.3/lib/commander/delegates.rb:11:in `run!'
from /Users/gwilson/.rbenv/versions/1.9.3-p392/lib/ruby/gems/1.9.1/gems/commander-4.1.3/lib/commander/import.rb:10:in `block in <top (required)>'

I've been thinking about the isolated-feature-branches approach that I used #89, and I've started toying with what that would look like for lesson content (#89 only uses it for pre-boot-camp setup). Ordinarily, I'd post this message to discuss@, but following @gvwilson's request, I'll open this one as an issue. I'm happy to move this discussion back into a mailing list if someone knows where this sort of workflow discussion belongs.

The isolated-feature branch workflow looks something like this:

1. New instructor getting ready for a boot camp

   a. Create a branch for the new boot camp, possibly in its own repository, cloning

   $ git checkout -b 2013-10-my-camp origin/master
   

   b. List possible subjects:

   $ less instructor.md
   

   c. For each subject you want to cover, merge the subject branch

   $ git merge git://github.com/wking/swc-boot-camps.git version-control
   …
   

   d. For each subject, pick and merge a tool

   $ less version-control instructors.md
   $ git merge git://github.com/wking/swc-boot-camps.git version-control-git
   …
   

   e. Publish your student-facing setup notes as you see fit for your tool/branch choices, possibly just by pointing students at the GitHub browser for your new branch.

2. Old instructor getting ready for another boot camp

   a. Create a branch for the new camp, based on something you've used in the past:

   $ git checkout -b 2013-10-my-camp 2013-04-my-last-camp-or-other-favorite
   

   b. You've been hearing good things on discuss@ about @wking's version-control-git branch, so you try switching over to it, dropping your old notes:

   $ git rm -rf version-control/git
   $ git commit -am "version-control/git: I don't want to maintain this anymore" 
   $ git merge git://github.com/wking/swc-boot-camps.git version-control-git
   

   c. Publish…

The drawback of this multi-branch approach is that you don't have an out-of-the-box experience (unless folks want to maintain "distribution" branches collecting a useful set of topic branches). The upside is that we don't have to agree on everything across tools and subjects before we can collaborate on a single subject/tool note set. It also makes maintainer-ship obvious; version-control-git is in my repository, so I'm going to maintain it, and that's where you should sent pull requests. If I'm doing a bad job, and jdoe starts an alternative branch with long-form notes and sexy graphics, it's an easy merge for interested parties to switch over. It also makes it easy for experienced instructors to grab some new testing stuff that they like, while keeping their personal shell lesson which they adore.

Thoughts?

Our lesson materials are written in a variety of formats, including HTML, plain Markdown, IPython Notebooks, and R Markdown. What tools can we find and/or build to help manage this? Some of the issues we need to consider are:

• make it really simple for instructors to get set up for creating and previewing lessons
• consistent appearance
• simple inter-linking
• incorporating lessons into the main web site

See also: #120 (metadata)

In the last couple of weeks some PR for shell's lesson have been create (some already merge) but a general review could be needed. (AFAIR @ahmadia is working on that).

The folders with shell content are:

• ./_includes/guide-shell,
• ./lessons/thw-shell,
• ./lessons/swc-shell and
• ./lessons/ref.

The last one have a cheat sheet in ./lessons/ref/shell.html.

We also have two IPython Notebook about shell (one of than in PR #93) but no link to them in the site:

• ./lessons/swc-shell/shell-filedir-instructor.ipynb and
• ./lessons/swc-shell/shell-overview.ipynb

Feel free to add any comment in this issue.

It's not obvious how to create a schedule such as:

April 10: Teaching from 4AM-11PM
April 11: Teaching from 8AM-10AM

Right now it appears that all time windows are shared.

History was effectively "reset" in the Great Fall Software Carpentry Migration of 2013. That is, all version control provenance, including original authors, editors, and change history is currently missing from the bc repository. The material is currently archived in boot-camps, and it would be good form for us to rebase any material in bc that derives from the boot-camps back onto the original commit history in boot-camps.

This is going to be relatively challenging and will involve some fairly aggressive rewriting of the commit history in bc. This meta-issue will collect a list of all content in bc that derives from boot-camps but is missing version history, describe the strategy for rebasing, and keep track of progress in injecting history back in.

It turns out we can do this without rebasing. See comment below.

lessons/swc-python/python-6-testing.ipynb needs to introduce setup() and teardown(), and needs a larger (realistic) example to motivate them.

Construct a lesson on R for intermediates in r/intermediate. (Oops, pointed to sql/intermediate at first).

@juliangarcia has suggested a few edits to these notebooks in #60, and I'd like to discuss an unrelated issue I spotted while looking at the notebooks. If everybody agrees, we can add this is as a rider to @juliangarcia's PR :)

I'm referring to the content here:

https://github.com/swcarpentry/bc/blob/gh-pages/lessons/swc-python/python-01-functions.ipynb

Viewable here: http://nbviewer.ipython.org/urls/raw.github.com/swcarpentry/bc/gh-pages/lessons/swc-python/python-01-functions.ipynb

Specifically this text:

fahr_to_kelvin's temp is not the same variable as fahr_to_celsius's temp. The two variables happen to have the same name, but since they're in different stack frames, they're as different as Einstein's glasses and Feynman's glasses.

These variables have the same name, occur in different stack frames, but point to the same object. I might correct the text to the following:

fahr_to_kelvin's temp_f is not the same variable as fahr_to_celsius's temp_f. The two variables are in different stack frames, so they could easily reference different objects! In this case, both variables reference the same underlying object, but you should not always assume this to be true.

Thoughts?

Construct lesson on Git for intermediates in git/intermediate.

Construct lesson on the Unix shell for intermediates in bash/intermediate.

Once metadata (#120) and tooling (#119) have been decided, create a set of one-minute screencasts showing people who want to add or modify lesson materials how to do that. For example, if we decide to use IPython Notebooks with tags on cells, we should show people how to mark up cells and how to run the tool that turns the master notebook into student and instructor notebooks. Similarly, we should show people how we want their Markdown formatted (what headings to use for what, how to lay out challenge questions), and walk them through the process of committing to the repo and/or reviewing things that are there.