All LGs: Check if content can be backed by references / literature

[gernotstarke]

We want our LGs to be "good" (explained in our readme

Therefore we should be able to add one or several references to EVERY LG.

From my point of view, this would add substantially to the curriculum - plus would we be able to base exam-questions on published sources...

[sippsack]

Question: we also have references to German books. Does it make sense to have a reference to a German book in the English version? Should we than reference different books in English/German or should we reference German books at all?

[gernotstarke]

Reality Check: Currently I estimate that 80% of all Foundation trainings are conducted in German. So, despite i18n, that language still has great relevance. I vote for keeping them for now...

[ulibecker]

Do we have actual data on the language? For me it is definitely more trainings in English than in German.

[gernotstarke]

Status 2023 (reported by iSAQB GmbH)

Numbers of FOUNDATION certifications:

DE 3108 EN 1295

These numbers support the thesis that German references are currently plausible and welcome.

[feststelltaste]

• Regarding the references: I agree that it would be great to see what is actually meant by some learning goals to avoid ambiguity and support participiants, trainers as well as exam question creators in their work.
• Regarding the language of the references: These should only be in English in the English version of the curriculum, otherwise they will NOT assist non-German speakers in carrying out their work.

[sippsack]

So then we should have English references as default in both translations and only German references in the German curriculum if no English reference is available

[skogsbaer]

I suggest to keep it simple and have the same references for the german and the english version. Having a german reference in the english text does not harm much. In some rare situations, such references in could even be helpful as nowadays tools exist to translate from german to english automatically.

[sippsack]

Next question of understanding: I don't see myself in a position to suggest references without reading a lot of books. How can we proceed so that we can efficiently compile a large number of concrete references?

[skogsbaer]

I will go through the whole curriculum and report places that would need a reference. In a second step, we can come up with the references.

[ulibecker]

I would be in favor of having only English references in the English version of the curriculum. Following a reference in the English curriculum and ending up on a German website or book feels weird - and does not really help with internationalization IMHO.

[alxlo]

So then we should have English references as default in both translations and only German references in the German curriculum if no English reference is available

That would make it even harder to maintain a good overview and might be confusing for students as well as for trainers and curriculum authors.

I propose the following:

• Keep a few (good) German references.
• We don't need a large number of references, just good ones. When we overwhelm our readers, they will miss out the good ones.
• Try to avoid German references (but not at all costs, translation tools are widely available)
• Have strictly the same references for English and German versions.
• Mark non-English references clearly. At least in the "References" section but possible also in the ref shorthands "[Lilienthal2018DE],[Zörner2021DE]".

[mikesperber]

I think that, while this is a laudable goal, it is unrealistic given the current literature landscape on software architecture, which is spotty and of varying quality. (Ha, I said "quality" - right there.) And as much as I like @gernotstarke's book - taking that as the sole authoritative source on something is problematic for obvious reasons. (@gernotstarke mentioned proven research in an e-mail - IMHO this basically doesn't exist for software architecture.) This doesn't mean we shouldn't try though - but for LGs that don't meet that standard we might still decide to keep them around, but should take some motivation to write something up ourselves. (@skogsbaer and I are currently working on a blog post about "sums and products", for instance.)

[sippsack]

So then we should have English references as default in both translations and only German references in the German curriculum if no English reference is available

That would make it even harder to maintain a good overview and might be confusing for students as well as for trainers and curriculum authors.

I propose the following:

• Keep a few (good) German references.
• We don't need a large number of references, just good ones. When we overwhelm our readers, they will miss out the good ones.
• Try to avoid German references (but not at all costs, translation tools are widely available)
• Have strictly the same references for English and German versions.
• Mark non-English references clearly. At least in the "References" section but possible also in the ref shorthands "[Lilienthal2018DE],[Zörner2021DE]".

To make things more complex: Carolas book is available in English and German. Should we reference the German book in the German translation and the English otherwise. Just kidding ... But seems we don't have a common sense. Some like to have German books as well others English only.

@mikesperber: I'm looking forward to the blog post about sums and products

[alxlo]

Ah, 'common sense' - the first passenger to abandon ship when the sea of confusion gets choppy. Perhaps we should rename it 'uncommon sense' and treat it like the rare treasure it is. zwinkersmiley But I think, there is no need to over-engineer. From my perspective, investing time in finding replacements or supporting language specific references for those very few sources does not provide sufficient return.

[sippsack]

Ah, 'common sense' - the first passenger to abandon ship when the sea of confusion gets choppy. Perhaps we should rename it 'uncommon sense' and treat it like the rare treasure it is. zwinkersmiley But I think, there is no need to over-engineer. From my perspective, investing time in finding replacements or supporting language specific references for those very few sources does not provide sufficient return.

Sorry, common sense was not, what I meant here. I should have asked deepl. I meant common understanding/opinion.

Maybe we'll wait until @skogsbaer has identified the places that need a reference. Maybe it is not a problem at all.

[mikesperber]

I occasionally teach Foundation in English, even though most participants are native German speakers. To them, German references even in the English curriculum would be useful.

[gernotstarke]

Important stakeholders of this initiative are...

• primarily YOU guys from the FOUNDATION working group: When creating more exam questions, we need some agreed-upon content to base these questions on, otherwise we will always struggle.
• secondary, people who DO NOT ATTEND our trainings, but prepare for the exam themselves. I don't care that much about those, it's their own responsibility to learn the topics.

Everybody attending accredited trainings shall get good-enough explanations (maybe backed by references) for the LGs.

Let's at least try to identify references - and be pragmatic with it. Avoid additional if/then in adoc.

[gernotstarke]

I write an ADR for that:

• we keep references in both EN and DE until further notice, at least for the V-2025
• we strive for learning content with references, but accept certain cases without references (let's call it mutually agreed content)

[skogsbaer]

There is now #533 that adds some references to LG-{1,2,3}.

I'm running somewhat out of time as the semester starts next week. I'll come back to this issue, but not before mid of October I guess.

[programming-wolf]

I also commented in one pull request. I don't like this idea at all, it looks horrible. Completely clutters the curriculum if every other sentence has a reference forced into it.

I think it's enough to have the references section at the end of the chapter. If you want to have it for each learning goal, add a separate section at the end of each learning goal, where you list references (including the pages/chapters of the books you're referring to).

[rhoadesre]

My two cents worth: in general, I agree that the R1 LGs should have references. However, my gut feeling is that this will take a lot of effort. I would suggest to delay it to the next release. I would add both English and German references, also in the English curriculum. Currently, the vast majority of our customers are German. As we become more international, we can add other references.

Would the references be to books, or specific pages in specific books for each learning goal. It would be helpful if we could point to certrain passages in specific books that back up the learning goal, but this would be a lot of effort. However, I think it would be worth it because it is currently difficult to determine what the "iSAQB opinion" to certain topics is.