Split long discussion points into separate files? Or drop untaught discussion?

[wking]

In swcarpentry/git-novice#71, @gvwilson suggested a 500–800 word range for disussion entries. That strikes me as a bit long for the current list-based suggestion. In fact, the novice Git lesson has already moved to using second-level headings. The list-based approach would work fine if the list entries were something like:

* For suggestions about composing commit messages, see $LINK, $OTHER_LINK, and $THIRD_LINK.

but with the longer-form entries I think we'd benefit from more structure. In fact, the current design docs say:

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.

If we decide to allow longer-form entries, I see two ideas for staying organized:

a. Add a discussion/ directory, and keep discussion as a table of contents with a list of short subject summaries referencing external docs or pages under discussion/.
b. Mirror MediaWiki and have an optional discussion/talk page targetted at each lesson (e.g. 01-one-talk.html.

Route (a) would allow more free-form entries, while (b) would help keep the discussion focused on a particular lesson page.

Personally, I'd rather avoid large bodies of untaught material in favor of linking out to external docs and further SWC lessons at the end of each lesson page in a “Further reading” or “References” section. Otherwise, I'm concerned that long, free-form discussion space will end up as a dumping ground for “we'd really like to teach this, but don't have time here”. If you have good material that's too advanced for your lesson, spin it off into a (mini) lesson building on the basic lesson! Then more advanced students/workshops can teach it explicitly, and it will get the presentational polish it deserves.

[wking]

Another possibility would be to have a single, few-minute long, skip-able block at the end of each lesson page. Although perhaps this content should come out of the existing lesson material where we've underestimated the teaching time (see the time-pressure discussion in swcarpentry/DEPRECATED-site#873). Then instructors who were on-schedule could cover the full lesson, and instructors who had fallen behind could skip the optional block and know they weren't missing critical information. That would keep the optional material in the time-counted, usually taught part of the lesson, which helps us stay focused on that page's goals and forces us to keep the delivery polished. It also avoids the difficulty of organizing and navigating bunch of unrelated discussion entries.

[iglpdc]

I really don't have a clear idea of what's supposed to be in discussion.md. It's addressed to learners, but not to be included in the lesson. The materials shouldn't possibly be part of an advanced or extra lesson (such materials should have their own lessons).

I think this is a similar situation to the Supplementary Materials in some scientific journals. And we should avoid the problem often seen in these journals were authors comply with the 4-page format, but sneak in a bunch of essential stuff in 36 pages of Supplements (I just did one of these :-) )

I see two things that could be included here. One are reference-type entries, short, linking to other sources. They should be here to avoid breaking the flow of the lesson. The other are actual supplementary materials, things that make no sense out of this lesson, are worthy to note, but not important enough to make it to the lesson. A good example of those could be the current entry on non-text files and Git in the git lesson.

Also, as most of these entries are going to be disconnected from each other, I think small files with one topic each would be great.

So, I'd go for @wking 's option a) above: a "References"/"Further Reading" file with list of short topics with links to external resources and exceptionally allowing longer entries. Longer entries should be developed by us, fitting in the category of supplemental materials, have their own file in a discussion/ folder, and a short link in the "References" file.

I think having entries in separate files would also allow easier remixing of these materials or upgrading them to short/advanced lessons.

[gvwilson]

I think each set of lesson maintainers should fill in `discussion.md` as they think best for now, and once we've got a couple of examples to generalize from, we can figure out what it _should_ be.

[wking]

On Tue, Mar 17, 2015 at 09:41:29AM -0700, Greg Wilson wrote:

I think each set of lesson maintainers should fill in
discussion.md as they think best for now, and once we've got a
couple of examples to generalize from, we can figure out what it
should be.

Sounds good to me. Until we have enough data to reach an informed
consensus, we can just link here to show that folks have the
flexibility to experiment.

[wking]

On Tue, Mar 17, 2015 at 09:41:29AM -0700, Greg Wilson wrote:

I think each set of lesson maintainers should fill in
discussion.md as they think best for now, and once we've got a
couple of examples to generalize from, we can figure out what it
should be.

Now that maintainers have been off on their own for a while, here's a
survey of what we have in the lessons listed on 1. Raw line counts:

$ for REPO in $REPOS; do wc -l $REPO/discussion.md; done | sort -nr
wc: swc-novice-matlab/discussion.md: No such file or directory
412 git-novice/discussion.md
345 python-novice-inflammation/discussion.md
139 hg-novice/discussion.md
53 shell-novice/discussion.md
37 make-novice/discussion.md
23 r-novice-inflammation/discussion.md
17 instructor-training/discussion.md
6 sql-novice-survey/discussion.md
6 r-novice-gapminder/discussion.md

Digging in in order of increasing complexity:

• sql-novice-survey and r-novice-gapminder have empty/fixme content.
• instructor-training has recommendations for contributions (which
  maybe belong in CONTRIBUTING.md or the README.md?).
• r-novice-inflammation has one 150-ish word discussion point (under a
  second-level heading) talking about errors when calculating means.
• make-novice has two discussion points under second-level headings.
  The first introduces parallel execution, and the second links a few
  blogs and tutorials about reproducible research with Make.
• shell-novice has three discussion points under second-level
  headings. The first apologizes for short command names, the second
  introduces ctrl+…, and the third talks about other shells besides
  Bash.
• hg-novice has three discussion points under second-level headings.
  The first is just a lead in for the discussion page itself, the
  second talks about ~/.hgrc, and the third is a mini-lesson (~100
  lines and ~650 words) on non-text files.
• python-novice-inflammation has three discussion points under
  second-level headings. The first is a brief list of debugging
  guidelines, the second is a mini-lesson (~140 lines and 750 words)
  on the call stack, and the third is a mini-lesson (~180 lines and
  ~810 words) on image grids.
• git-novice has eight discussion points under second-level headings,
  and the initial points are much like hg-novice's. The first is just
  a lead in for the discussion page itself, the second talks about
  ~/.gitconfig, the third is ~40 lines on styling the log, the fourth
  is a mini-lesson (~100 lines and ~600 words) on non-text files, the
  fifth is a mini-lesson (~50 lines and ~200 words) about removing
  files with ‘git rm’, the sixth is a mini-lesson (~60 lines and ~230
  words) about removing files with ‘rm’, the seventh is a mini-lesson
  (~40 lines and ~140 words) about renaming files with ‘git mv’, and
  the eighth is a mini-lesson (~60 lines and ~260 words) about
  renaming files with ‘mv’.

So lesson-example and instructor-training are the only places using
bullet points. instructor-training is the only place that lists
contribution suggestions. make-novice is the only place with a brief
list of additional resources. And the rest all collect useful tidbits
that are usually about a quarter of a standard topic (which seem to
usually run 200 to 500 lines). The python-novice-inflammation
discussion point on image lists is roughly the same size as their
02-loop.md.

I still prefer splitting the mini-lessons out into intermediate
lessons if we don't have time to cover the material during the usual
lesson.