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
teaching-guidelines document.

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
     unfinished topics.

     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
     verbosity.

     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:

     https://github.com/mdadams/SG20/tree/mdadams

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:

     https://www.ece.uvic.ca/~mdadams/sg20/guidelines_for_teaching_cpp.html

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:

     https://github.com/cplusplus/SG20/blob/master/Readme.md

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.

Regards,
Michael

---
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