[u-u] Course design (was Re: jobs @ rakuten/kobo)

[pub08-uu at davor.org]

On Sat, Aug 05, 2017 at 01:27:38PM -0400, arocker at Vex.Net wrote:
> [...] I'm seriously thinking of
> making commenting the first [course] topic, before introducing any actual commands.
> Then create no-op scripts that are merely a plan for the desired
> processes, and proceed to fill out the functions underneath the comments
> describing them.
> 
> Does that sound like too much of a departure from the traditional sequence
> of a language course, or otherwise weird, to be accepted?

That depends partly on your audience, I think.

If this is a software development course that happens to use Perl
6, then absolutely go this route!  In that case, it's the
big-picture stuff that matters, and your choice of language is
essentially an implementation detail.

But if Perl 6 is the focus (e.g. if it's a course for experienced
devs who want learn that specific language), then, well, the
focus should probably stay on Perl 6.  Some asides on testing or
documentation or OO-in-general or whatever are OK, but they
should steer well clear of overwhelming the core material -- the
language itself.

Basically, speaking as someone who's in a position to write this
email :-), if I were taking a Perl-6 course, it would be because
that's what I want to learn.  If I wanted a course on software
engineering, I'd sign up for that instead, and would be equally
miffed if it spent a huge amount of time teaching the language
the course happened to be taught in.  But an undergrad CS student
would feel very differently.

Then again, you did say "training".  If that means corporate, to
bring a team up to speed, somewhere in between might be
appropriate.  Why not discuss the question with the people who
are paying you to design the course, and perhaps also with the
potential students?


Supposing the big-picture stuff is in fact appropriate for the
course...

I'd broaden "commenting" to "documentation", of which the former
is only one aspect.

(I'm not saying anything new or profound in what follows; this is
stuff we all know in our guts.  But perhaps bringing it (back?)
into consciousness will be a useful exercise.  It has been for
its author :-) )

It would be useful to cover the difference between user vs.
internals documentation (defining "user" very broadly).  It turns
out "external documentation" is a term, so that's what I'll use.

Basically, external documentation covers the benefit (buzzword:
"business value") your code provides and how to make use of that
value.  ISTM that this is the stuff you were talking about
writing first.

Internal documentation describes how the code does what it does,
and why it does it that way.  This, I think, is what someone else
here described as a workaround for bad design.  (It can be that,
certainly, but IMO internal docs definitely have their place -- a
description of the overall architecture is one example.)

The two have different purposes and different audiences, so I
believe it's best to consider them as separate cases.  Conflating
them just confuses things.

For example, good code design does indeed reduce the need for
internal documentation.  What reduces the need for external
documentation is good *interface* design -- whether that's a GUI,
an API, a CPU architecture, or the knobs on a kitchen stove (see
Don Norman's work).


It occurs to me that one can look at comments per se as not being
intrinsically on that axis at all.  Whether a given sentence of
text physically lives within or external to a source-code file is
somewhat (not entirely) orthogonal to the question of its target
audience.  In other words, "internal" and "external" are
overloaded terms in this context, and it's important to keep in
mind which sense one's talking about.

To some extent, it's the language/ecosystem that determines which
representation is best for which information.  E.g. in the UNIX
world, the ultimate source (i.e. human-edited version) for
external documentation tends to be the man page's [nt]roff
source, but in Perl it's the pod sections within the Perl files.
For a Java module, it's Javadoc comments (which are real /*-style
comments, just formatted specially).

Similarly, internal documentation typically lives in comments
near the code it's describing, but there are sometimes external
files containing internal documentation -- a lot of the stuff in
the Linux kernel's Documentation/ directory, for example.  (The
same directory also contains a lot of external documentation, but
IMO that's a bug, not a feature).


The same distinction applies to testing.  It's been said that:
    Unit testing helps you to build it right.
    Integration testing helps you to build the right it.
    
In other words, they correspond to internal and external docs
respectively.  (Leaving aside the question of whether unit tests
should be black-box or not; that's a whole different
war^H^H^Hsubject.)

  - Eric