Create Section for References

[programming-wolf]

• Demonstrate how every (!) learning goal has to define its own references section
• Fix configuration to also include text that is not enclosed in language tags
• Remove bibref variable to trigger warnings: Once every learning goal of a chapter has its own references section, the references file causing the warning has to be removed.
• Fix broken reference to glossary
• Fix broken learning goal reference

See #535

[github-actions]

Build Successful! You can find a link to the downloadable artifacts below.

Name	Link
Commit	fafd808
Logs	https://github.com/isaqb-org/curriculum-foundation/actions/runs/11217923631
Download	https://github.com/isaqb-org/curriculum-foundation/suites/29305157983/artifacts/2024411496

[gernotstarke]

Before merging I want to emphasize that THIS IS EXPERIMENTAL, and we need to make sure the new layout works in practice. For example, in LG-04-03 we reference different notations, imho easy to read.

Would you really prefer moving these references out to a new section?

[programming-wolf]

Before merging I want to emphasize that THIS IS EXPERIMENTAL, and we need to make sure the new layout works in practice. For example, in LG-04-03 we reference different notations, imho easy to read.

Would you really prefer moving these references out to a new section?

Yes, I would add them to their own section. We could duplicate them in this case.

[skogsbaer]

I see no good reason to duplicate these references (actually, avoiding duplicates is one reason given by @gernotstarke in #535 to have a dedicated section for references in the first place). Duplicate references are harder to maintain and, in the situation shown above, do not add value for the reader.

Imho, putting a reference close to the term that needs to be backed up by the reference, makes it easier for the reader to follow the chain of arguments. I would suggest the following convention:

• If a reference applies only to specific aspect of a learning goal, embed the reference within the text and try to keep the reading flow.
• If a reference is of more general nature and applies to many aspects of a learning goal, put it in the reference section of the learning goal.

[programming-wolf]

Then I recommend to remove them from the text altogether. Have the references section for the learning goal, that's it.

[skogsbaer]

That make's it worse for the reader.

[programming-wolf]

I think it is a lot cleaner like this and way easier to read. We're not writing a book or a scientific paper, it's a curriculum that focuses on the content and is supposed to provide additional information (references) to both trainers and trainees.

[gernotstarke]

That screenshot shows exactly the problem: Now the references lack the specific context they had before. Without prio knowledge, it is NOT CLEAR that [Brown] explains the C4 notation.

I will go through the rest of the LGs and check if that happens often, or if LG-04-03 is the only one with the need for subtopic-specific references.

[programming-wolf]

Then we should adjust the reference name to be [Brown C4 Model], for example? 😉

[gernotstarke]

This is just a special case. Imaging <>, that book is used for all kinds of topics...