Subject: Suggestions for Improvements to Teaching-Guidelines Document
From: Michael Adams (mdadams_at_[hidden])
Date: 2021-03-09 23:01:26
Dear SG20 Members:
Since the time of our last SG20 meeting, I have been giving considerable
thought to the teaching-guidelines document that we are currently
developing. This mainly arose from my experiences of attempting to
complete the content for a new topic for this document. Generally, I
found this process to be much more difficult than it should be. As a
consequence, I became sidetracked thinking a lot about how to make
it easier to contribute to the document as well as how to present the
content in a manner that makes it maximally helpful to people as early
as possible. In this regard, I would like to share some of my thoughts.
Hopefully, some of these ideas might prove helpful to our work on the
So far, we have been using what I would call a bottom-up approach
to the development of the teaching-guidelines document. That is, we
have selected a number of relatively narrow topics and then produced
learning outcomes for them. This has been done at the expense of not
having any substantive top-level information to guide the development
of the document. The more I think about this, the more I feel that this
is a mistake, as this bottom-up approach suffers from numerous problems
such as the following:
1) There are no formal guidelines to help contributors, aside from
some very basic instructions in the template for topics. While these
instructions are helpful, they do not provide sufficient guidance
in terms of helping the contributor understand the bigger picture.
For example, it would be unreasonable to expect all C++ experts
to know about learning outcomes (e.g., what are they, how does
one prepare good ones, etc.).
2) A contributor has no context for the content that they are
developing (i.e., they do not know how this material will be
referenced from the larger document).
3) A contributor cannot know what other parts of the document are
likely to be relevant to the material that they are developing,
as very many units/topics have not yet been identified anywhere.
This makes it impossible for contributors to reference sections
that are planned to be added later (since it is not known what these
sections will be).
4) The document is less likely to be useful until it is very
nearly complete. In contrast, a top-down approach is more likely
to yield a document that could be useful to others earlier because
some units/topics can be given broad coverage initially and then
split later, allowing all topics to be completed earlier (with broad
less-detailed coverage initially) as opposed to having many narrow
5) It discourages planning and organizing the full set of the material
to be covered from the outset. I strongly believe that having a
list of all of the topics to be covered from the start would be
immensely helpful. This would help to ensure that everything fits
together better in the end (which is a significant concern of mine).
6) With a bottom-up approach, it is easier for topics to become
unbalanced (i.e., high coverage in some areas while relatively
little or none in others) or too narrow in scope. For example, I would
recommend merging the items for "parameter passing by value" and
"parameter passing by reference" to simply "parameter passing".
One can always split the items apart by proficiency level of
the learning outcomes if necessary (since we have three levels of
proficiency). I would also merge "rule-of-five" and "rule of zero"
(and more generally "rule-of-N" for your favorite N ;-) into something
like "guidance on special member functions".
I would also make the following additional recommendation:
7) The "foundational" and "main" proficiency levels be renamed as
"basic" and "intermediate", respectively. I have never seen "main"
used in any literature on teaching, but "intermediate" is common.
8) If a documentation is added on what learning outcomes are in the
main document body, then these can be removed from the template.
Having all of the template boilerplate in the final document
makes things more difficult for the end user to parse, due to high
9) It would be very helpful to automatically build the
teaching-guidelines document and pushing the result to a GitHub
Pages site with each commit to the master branch.
[I can help with this if desired.]
Of course, it is easy to criticize, and less easy to offer solutions.
While I do not claim to have all of the answers, I have tried to capture
some of the ideas that I have had so far in a personal fork of the SG20
Git repository. Some of the changes in my fork are related to the issues
raised above. The fork can be found at:
All of my changes are on the branch called mdadams. For your convenience,
I have built a copy of the teaching-guidelines document from this fork
and placed it at:
If you would prefer to build a copy yourself, I placed some brief
instructions on how to do this in the top-level README document.
For comparison, the current official SG20 document is:
I would value feedback on whether the changes that I have made are seen as
beneficial or not by others. Please note that this fork should be viewed
as a work in progress. I have tried to finish enough work in advance of
the upcoming SG20 meeting so that people can get a sense of some of the
types of changes that I am advocating. Hopefully, some of this may spur
some further discussion and innovations during the upcoming SG20 meeting.
--- Michael Adams, Associate Professor, Ph.D., P.Eng., IEEE Senior Member Dept. of Electrical and Computer Engineering, University of Victoria PO Box 1700 STN CSC, Victoria, BC, V8W 2Y2, CANADA E-mail: mdadams_at_[hidden], Web: https://www.ece.uvic.ca/~mdadams
SG20 list run by email@example.com
Older Archives on Google Groups