Date: Wed, 2 Mar 2022 16:02:26 -0800 (PST)
Hi Everyone,
On February 23, the "North-America timezone" subgroup of SG20 met to
develop a preliminary draft of the content for the "Headers" topic under
the "Compilation Model" module in the C++ teaching guidelines document.
The meeting participants consisted of Robert Douglas, Victor Eijkhout,
and myself. The latest published version of the guidelines document
(which does not include the "Headers" topic) is available at:
https://cplusplus.github.io/SG20/latest/
The work on the "Headers" topic is associated with the following pull
request on GitHub:
https://github.com/cplusplus/SG20/pull/74
During the above meeting, we encountered a number of issues that were
somewhat detrimental to making fast progress on developing the content
for the "Headers" topic. Since these issues are likely to impact others
who are trying to contribute content for other topics, we decided to
provide some feedback (via the SG20 mailing list) based on our experiences
during the above meeting. In what follows, I have tried my best to
capture the sentiments expressed in this meeting.
The most significant difficulty that was faced is probably best summarized
as a lack of clarity about exactly how the topic being developed would
fit with the other content that is to be later developed. This led to
questions like the following:
1. To what extent are dependencies acceptable for a given topic
being covered? What other topics should a particular topic be
allowed to depend on? Should there be guidelines for deciding
what level of dependencies to allow? The answers to these
questions are not clear. At one extreme, having a very high
number of dependencies will greatly increase the number of circular
references in the guidelines document and also likely make the final
document much more difficult for end users to navigate. At the other
extreme (i.e., very few or no dependencies), one might be too
constrained in what can be discussed due to the need to avoid
introducing additional dependencies.
2. What is the true intended scope of given topic being developed?
For example, in the case of our meeting, the topic was "Headers".
The topic of "Headers" could be interpreted as having either a very
narrow or very broad scope. In the case of a more narrow scope,
the focus might be more on the preprocessor include directive itself
and what types of source code are appropriate for placement in a header
(without relying on knowledge of classes, templates, modules, or other
such language features). With a broader scope, the focus could start
to talk about the many interactions between headers and other language
features such as classes, templates, modules, and so on. As the scope of
topics are broadened, the amount of redundancy and overlap between
topics also grows significantly, which will likely make navigating
the document more difficult for the end user as well as making the
document more difficult to maintain by SG20 over time.
3. Is it implicit that higher level coverage of a topic requires coverage
of the topic at the lower levels as a prerequisite? For example,
when covering a topic like "Headers" at the advanced level, it is
implicitly assumed that the student already has seen coverage at
the foundational and main levels? If this is implicit, this eliminates
the need (in the text for a topic) to repeatedly state that the
required background for level X includes the background for level
Y for each Y < X.
Note that items 1 and 2 above are very much interdependent as the scope
of coverage will also greatly impact the number of dependencies.
It was felt, during our meeting, that a discussion of the above issues
within the SG20 group as as whole would be highly beneficial. In order
for this project to be successful, we need to minimize barriers to those
who might be interested in preparing content, and some of the issues
identified above may serve as barriers to contributors (including
the members of SG20 itself).
Just before closing, I would like to make a brief suggestion, which
is based solely on my own personal opinion and may or may not reflect
the opinion of Robert and Victor. In light of the above, my personal
feeling is that it would be highly beneficial to take a closer look at
the guidelines document from the top down. This might entail something
like the following:
1. Identify the areas of C++ teaching that are not well covered
(or have no coverage) by the modules/topics identified in the current
guidelines document, and possibly perform some further refinement
of the existing modules/topics.
2. Try to sketch out the intended scope of each of the modules/topics.
In other words, I am advocating that we spend a little more time on the
planning of the overall document structure before investing too much more
effort on the finer details of developing individual topics. By doing
something like this, we would gain a much better understanding of what all
will be covered in the final guidelines document and the scope of coverage
for the various modules/topics. This would help to address the issues
identified earlier in this email. In turn, this would help to remove
obstacles to those who would like to contribute content for the various
topics in the guidelines document. Also, as an important side benefit
of this additional planning, the various parts of the document are
much more likely to fit together in the end.
[Note to Robert Douglas and Victor Eijkhout: I have tried my best to
capture the various sentiments expressed in our recent meeting. If I have
omitted anything important or not clearly/accurately conveyed some aspects
of what was discussed, please jump in and correct me.]
Regards,
Michael
On February 23, the "North-America timezone" subgroup of SG20 met to
develop a preliminary draft of the content for the "Headers" topic under
the "Compilation Model" module in the C++ teaching guidelines document.
The meeting participants consisted of Robert Douglas, Victor Eijkhout,
and myself. The latest published version of the guidelines document
(which does not include the "Headers" topic) is available at:
https://cplusplus.github.io/SG20/latest/
The work on the "Headers" topic is associated with the following pull
request on GitHub:
https://github.com/cplusplus/SG20/pull/74
During the above meeting, we encountered a number of issues that were
somewhat detrimental to making fast progress on developing the content
for the "Headers" topic. Since these issues are likely to impact others
who are trying to contribute content for other topics, we decided to
provide some feedback (via the SG20 mailing list) based on our experiences
during the above meeting. In what follows, I have tried my best to
capture the sentiments expressed in this meeting.
The most significant difficulty that was faced is probably best summarized
as a lack of clarity about exactly how the topic being developed would
fit with the other content that is to be later developed. This led to
questions like the following:
1. To what extent are dependencies acceptable for a given topic
being covered? What other topics should a particular topic be
allowed to depend on? Should there be guidelines for deciding
what level of dependencies to allow? The answers to these
questions are not clear. At one extreme, having a very high
number of dependencies will greatly increase the number of circular
references in the guidelines document and also likely make the final
document much more difficult for end users to navigate. At the other
extreme (i.e., very few or no dependencies), one might be too
constrained in what can be discussed due to the need to avoid
introducing additional dependencies.
2. What is the true intended scope of given topic being developed?
For example, in the case of our meeting, the topic was "Headers".
The topic of "Headers" could be interpreted as having either a very
narrow or very broad scope. In the case of a more narrow scope,
the focus might be more on the preprocessor include directive itself
and what types of source code are appropriate for placement in a header
(without relying on knowledge of classes, templates, modules, or other
such language features). With a broader scope, the focus could start
to talk about the many interactions between headers and other language
features such as classes, templates, modules, and so on. As the scope of
topics are broadened, the amount of redundancy and overlap between
topics also grows significantly, which will likely make navigating
the document more difficult for the end user as well as making the
document more difficult to maintain by SG20 over time.
3. Is it implicit that higher level coverage of a topic requires coverage
of the topic at the lower levels as a prerequisite? For example,
when covering a topic like "Headers" at the advanced level, it is
implicitly assumed that the student already has seen coverage at
the foundational and main levels? If this is implicit, this eliminates
the need (in the text for a topic) to repeatedly state that the
required background for level X includes the background for level
Y for each Y < X.
Note that items 1 and 2 above are very much interdependent as the scope
of coverage will also greatly impact the number of dependencies.
It was felt, during our meeting, that a discussion of the above issues
within the SG20 group as as whole would be highly beneficial. In order
for this project to be successful, we need to minimize barriers to those
who might be interested in preparing content, and some of the issues
identified above may serve as barriers to contributors (including
the members of SG20 itself).
Just before closing, I would like to make a brief suggestion, which
is based solely on my own personal opinion and may or may not reflect
the opinion of Robert and Victor. In light of the above, my personal
feeling is that it would be highly beneficial to take a closer look at
the guidelines document from the top down. This might entail something
like the following:
1. Identify the areas of C++ teaching that are not well covered
(or have no coverage) by the modules/topics identified in the current
guidelines document, and possibly perform some further refinement
of the existing modules/topics.
2. Try to sketch out the intended scope of each of the modules/topics.
In other words, I am advocating that we spend a little more time on the
planning of the overall document structure before investing too much more
effort on the finer details of developing individual topics. By doing
something like this, we would gain a much better understanding of what all
will be covered in the final guidelines document and the scope of coverage
for the various modules/topics. This would help to address the issues
identified earlier in this email. In turn, this would help to remove
obstacles to those who would like to contribute content for the various
topics in the guidelines document. Also, as an important side benefit
of this additional planning, the various parts of the document are
much more likely to fit together in the end.
[Note to Robert Douglas and Victor Eijkhout: I have tried my best to
capture the various sentiments expressed in our recent meeting. If I have
omitted anything important or not clearly/accurately conveyed some aspects
of what was discussed, please jump in and correct me.]
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: http://www.ece.uvic.ca/~mdadams
Received on 2022-03-03 00:02:42