@Michael Adams <mdadams_at_[hidden]> I agree it's time to re-group on
lessons learned and refine from the top. I expected we'd need such. These
small groups are doing precisely what we hoped for: Give us some bottom-up
experience to inform the top-down. I presume we will iterate repeatedly on
this, in such a way, for a while. I do appreciate your framing of the
issues we hit, though.

For now, I believe our primary blocker was how much to put into "Advanced"
section. It could certainly balloon quickly talking about using "inline"
for function definitions, or using "detail" namespaces for things you dont
want users of your header to rely on, and so on forever. What I think we
lacked was awareness of what other modules may come later that would
include such information, to help inform how we scope the module.

Also, the simple question: Do we need to keep reciting "Includes everything
in Foundational/Main"? Or is that implied?

On Thu, Mar 3, 2022 at 3:40 AM JC van Winkel via SG20 <sg20_at_[hidden]>
wrote:

> 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
>>
> --
> SG20 mailing list
> SG20_at_[hidden]
> https://lists.isocpp.org/mailman/listinfo.cgi/sg20
>