[clug] Writing Training Materials

Bryan Kilgallin bryan at netspeed.com.au
Fri Mar 24 11:49:02 UTC 2017

Thank you, Andrew:

> My recommendation is to dive in and write the part you know (the
> exercises), from there I find the formal structure generally just
> falls out.

Would you follow the advice of a primary-school teacher, on the 
technicalities of computer-engineering? Then why similarly copy the 
instructional methods of engineers?

> It's different for each audience so don't spend too much
> time agonising over it.

Exactly--and we haven't been told who the audience is! For example, what 
is their prior experience with the subject-matter?

> The best part about online training materials
> is that it's easy to link out to other things for those who are having
> trouble.

The examples given, seem to be textual. There seems little mention of 
graphical, audio, or video media.

> I've used wikibooks for this in the past:

I don't see song-and-dance there!

Where is the theatre? What about audience interaction?

> More recently I've used readthedocs in combination with sphinx to
> write API documentation and tutorials, it's backed by github and has
> great dashboard tools that allow you to check that your code examples
> work with a dashboard against the current API.

Are you going to draw the illustrations freehand?

> Depends on if you are writing code tutorials though.

How are you going to connect emotionally with the learner?

> I've also used plain text files (see below for an example).

That won't exercise your theatrical skill!

> In this
> case the workshop was run as a 30min introductory lecture on the
> science and motivation of why to do this followed by a 1 hour
> tutorial.

 > Developing affect requires involving the audience personally.

> So you have to adapt the material to suit each time you
> teach it.

Regurgitating content--is not all that learning is about!

> You already acknowledge that it's going to change over time
> and this is a good thing.

There is no mention of how the experience-manager is to develop their 
own expository skill.

> I find the best courses are those that are
> continually updated.

There has been no mention of assessment or evaluation!

> Others have suggested exhaustive reviews and needs analysis, this
> might work for those with 6 months of free time on their hands and an
> army of helpers to agonise over the design of the course and
> everything in it.

Dropout is a good measure of negative affect.

> I was forced to go through a needs-analysis,
> macro-design, micro-design, etc

Engineers aren't chosen for their performing-arts repertoire!

> It was the most frustrating waste of time I can remember in a long
> time.

Working on something effective, does require effort!

> My view is that there's no point pontificating and asking your
> audience about how they'd like to be taught what they don't know.

Democracy isn't a forte of engineering faculty!

> Take
> a crack at it and respond to feedback instead, I find it much more
> efficient.

Like ripping into code without considering requirements!

> Good luck, and just start writing, starting is the hardest part!

Count me out for that learning experience.

More information about the linux mailing list