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