Hi Michael,

Thank you for your deliberations, and thank you Robert and Victor for working together on the headers subject.  The EMEA timezone subgroup of SG20 also came together (Feb 21) and will come together again March 7. This subgroup comprises Bogusław Cyganek, Florian Sattler and myself.  We worked on the topic "Declarations" and next time it will be "definitions".  We were happy with the result we got from the "Declarations" discussion. Florian will create a pull request based on our shared Google doc we used (watch this space :-)

Regarding your questions, see inline:

On Thu, Mar 3, 2022 at 1:02 AM Michael Adams via SG20 <sg20@lists.isocpp.org> wrote:
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.

Some dependencies are unavoidable.  For example, in the "declarations" topic, we mention the word "definition" but defer explaining that to the definition topic.
So it is all about a fine balance.  I know, it is easy to say "not too much and not too little" but I think it is up to the authors.  As we get more topics done we can see what works and what doesn't and can make course corrections.  I am just happy we get some topics off the ground.  We can always fix things.
Having said that, we (EMEA subteam) too noticed this is not trivial.
 

   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.

I would keep the scope relatively narrow.  For example, we have a topic called "declarations". You can give a few examples of what to put in a header file, and then refer to the specific topic for that (in this case declarations.)

For example, in your "main" section for "headers", you have:
4. Explain the meaning of the one-definition rule and how it applies to headers

I think a headers chapter of a course should *mention* the ODR, but not explain it - that would be something for the "definitions" chapter of a course.


   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.

I agree with your point, still we have the "required knowledge" item in our template and it might be the case that at the level N+1, you need to require extra things than just level N.
We could consider eliding "required knowledge" if the only required knowledge for level N+1 is what is in level N - What do people think?
 

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.

I see your point.  This is all new to us, and personally, I would like to have a little "prototyping" : do a few topics and then see how we need to adjust to make the process workable and the end result better.

Florian,Boguslaw, what do you think?

Thanks for your feedback and I am happy with the good discussion!

JC

 

[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@ece.uvic.ca, Web: http://www.ece.uvic.ca/~mdadams
--
SG20 mailing list
SG20@lists.isocpp.org
https://lists.isocpp.org/mailman/listinfo.cgi/sg20