Hi Damien; thanks for your mail - I'm glad you found the process easier
than it used to be. (For those who haven't seen it,
http://swcarpentry.github.io/slideshows/creating-lesson/index.html has
just been updated, along with the docs at
https://github.com/swcarpentry/lesson-example and the example at
http://swcarpentry.github.io/lesson-example/).
Regarding sub-headings, when I look at
http://damienirving.github.io/capstone-oceanography/02-data-processing.html,
I see three shorter pages struggling to escape - in particular, I think
it would be natural to have a challenge exercise or two at the end of
each of the sections, which is how I'm currently figuring out where to
break pages. I've been wrong about lots of things, though, so I've
opened an issue for discussion:
https://github.com/swcarpentry/lesson-template/issues/220
I propose we give it a week for comments, then see if there's a consensus.
Cheers,
Greg
On 2015-04-04 10:01 PM, Damien Irving wrote:
Hi Greg,
I just went through the process of converting my existing capstone
example for oceanographers (which was in an IPython notebook) to the
lesson template:
https://github.com/DamienIrving/capstone-oceanography
I had never previously created a lesson in the official Software
Carpentry format and I found the new process to be very easy to follow
and execute. My only comment is on the "make check" advice around
sub-headings within lessons. In particular, it says:
/"The topic page should not have sub-headings outside of special
blocks. If a topic needs sub-headings, it should be broken into
multiple topics."/
I use sub-headings extensively to add clarity to my lesson notes (e.g.
http://damienirving.github.io/capstone-oceanography/03-data-provenance.html).
They are particularly useful when I'm reading off the notes while
teaching, because in a teaching situation you often have to scan the
page quickly looking for obvious breaks like sub-headings.
I guess I'm wondering if we could relax/modify the rules around
subheadings? Perhaps level 1 headings imply a new topic (because I do
appreciate the rationale behind trying to split the lessons into
smaller topics), while level 2 down can be added within a topic to
enhance clarity, or something like that?
Cheers,
Damien
On Fri, Apr 3, 2015 at 8:04 AM, Greg Wilson
<[email protected]
<mailto:[email protected]>> wrote:
Hi,
I've updated the slideshow that explains how to create an entirely
new Software Carpentry lesson repository - please see:
http://gvwilson.github.io/slideshows/creating-lesson/index.html
for the rendered version, and:
https://github.com/swcarpentry/slideshows/pull/21
for the pull request. Comments would be appreciated, but please
note that this describes the world as it *will* be once we finish
splitting the 'core' and 'gh-pages' branch of the
'lesson-template' repo into separate repositories - we don't want
to finalize that until the docs are ready to roll.
I'd be particularly grateful for reviews from people who *aren't*
regular contributors - we need a fresh look at this from people
who aren't already familiar with it to make sure it's comprehensible.
Thanks,
Greg
--
Dr. Greg Wilson | [email protected]
<mailto:[email protected]>
Software Carpentry | http://software-carpentry.org
_______________________________________________
Discuss mailing list
[email protected]
<mailto:[email protected]>
http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org
--
Dr. Greg Wilson | [email protected]
Software Carpentry | http://software-carpentry.org
_______________________________________________
Discuss mailing list
[email protected]
http://lists.software-carpentry.org/mailman/listinfo/discuss_lists.software-carpentry.org
