maintainers.md

[prechelt]

Issues with the structure and content of docs/maintainers.md.

Relates to issues #29, #30, which talk about the individual parts of the functionality described in docs/maintainers.md.
The present issue should pertain to the cross-cutting concerns (only), but you should not expect this delineation to be fully obeyed.

[prechelt]

Severe problems with structure and perspective

I have attempted to read maintainer.md and felt I needed to rework it heavily in order to make sense of it, because things were presented in an order that seemed very arbitrary, rather than logical, many helpful headings were missing, etc. It did not feel like a documented composed by an intelligent human being. See 1b8d05e for the changes.

Some comments on what I found:

• The file should have been called maintainers.md (akin to authors.md, instructors.md, etc.), but was called maintainer.md (now changed)
• It was not mentioned in mkdocs.yaml and thus was not included in https://sedrila.readthedocs.io (now changed)
• It did not obey the style suggested by authors.md regarding the title and regarding the numbering of sections (now changed)
• The content was not user-oriented:
  • The ordering of material was not a good ordering for understanding, nor like the order in which users would have to do things (now changed).
  • There was hardly any initial explanation what the point of the functionality was (TODO)
• Assumptions were not spelled out (TODO)
• Several statements pertained to propra-inf although that is a dependent project about which sedrila should know as little as possible (now changed).
• Those statements did not, however, actually mention propra-inf.

I will need to look further into the substance of the content another time.

[prechelt]

itree.zip and the need for a build

3.1.1. states "Program testing requires itree.zip to be built first. This directory is created during course building"

What is build during a build is a file itree.zip. The directory itree.zip is the source.
How does such an utterly wrong statement make it into the documentation when the author of the respective functionality is also the author of the documentation? It does not.

I said this before and I say it again now (expect me to become seriously angry if I encounter a similarly blatant case a third time):
Using AI for generating code and documentation is fine if it is a productive approach for you.
But you have to clean up the results until they are high-quality outputs suitable for the goals of sedrila and propra-inf. Failing to do this is not acceptable.
You are wasting my time, of which I have preciously little, and by doing so you are wasting the time of everybody else who is waiting on review feedback from me.

[prechelt]

Documentation readiness

In #29 you write that the documentation is far from complete. I guess that refers to my "Severe problems..." comment above and I guess it meant to imply that my review was premature.

However, on 2025-10-26 21:34 you had written on Discord that you had checked and adapted the documentation, which sounds perfectly review-ready to me.
I would like to be able to rely on such statements.
I would also like to be able to find them here in the issue tracker rather than in a variety of other channels.

Please understand that the documentation is the only sensible starting point for me when I start reviewing your new functionality. At the documentation level, I get an overview and can think at a requirements level. This saves much reverse-engineering effort when looking at the code later and allows me to make the most important points early rather than requesting you to make lots of lower-level changes first and then possibly later asking you to throw out large parts and re-implement them in a very different way.

[RYZENNAVI]

Feedback on the current situation

1. I had been focusing mainly on implementing features and paid not so much attentation to the documentation, because I initially thought the features were still under development. Moreover, since we had already gone through several rounds of discussions about these features, I assumed that as a reviewer, you would focus more on the actual code changes based on previous iterations rather than the detailed structure of the documentation. However, I now understand this point and I will make sure to improve the documentation after implementing new features.

2. Many of the contents and structures you modified in maintainers.md were actually written by me, not by an AI (although I sometimes use Google Translator for translation, which might make the writing seem a bit less natural). However, you said that this was due to my failure to clean up AI-generated content, that’s a misunderstanding. The real reason was my negligence regarding the importance of documentation.

3. You have already shown strong dissatisfaction twice with the results related to AI tools. However, in my view, both cases were primarily caused by human factors (based on misunderstanding and information asymmetry), and I feel it’s necessary to explain them:

   • The first case was because I used a hardcoded whitelist mechanism in maintainer --check-links. In my understanding, sedrila and Propra were closely related, but before implementing it, I wasn’t informed or see in existing documentation, that sedrila placed such a strong emphasis on decentralization. I extracted and printed those whitelisted links clearly for your review, but this unexpectedly led to a very angry reaction.

   • The second case happened because I focused on feature implementation and forgot to adjust the documentation format (such as numbering and structure) to align with documents like author.md. My workflow is to first record the essential functionalities, then later or finally (until this feature is fully implemented and everything has settled down) refine and beautify the descriptive documentation. Otherwise, the documentation would undergo a lot of meaningless revisions during development. Of course, now I understand your expectations for documentation formatting, and I will start aligning with your workflow.

However, your recent reaction and the “final warning”: that you would be very angry if a similar issue occurs a third time, implies that I should not make such mistakes at all, even in minor details like the descriptions in itree.zip. That’s difficult, because the feature structures have become complex, and I need to read a large amount of code and text. I cannot guarantee absolute perfection, only do my best (Therefore, after reading the feedback, I immediately supplemented the information #29 (comment) in the --program-check with any inconsistencies features in the documentation). After reading such feedback, I’ve also been feeling increased pressure, which is not beneficial for development progress.

Although I have completed many tasks in ProPra, that experience alone isn’t enough for me to instantly understand all the specific rules and requirements that need to be followed in another repository like sedrila. I still need time to learn.

I will continue to modify the documentation further based on your feedback.

[RYZENNAVI]

My thoughts on the feedback

In addition, I hope that in the future you can try to be more certain when giving feedback, so that we can avoid a large amount of rework later on.

I have three examples here:

1. When I initially implemented author --validate-snippets and author --validate-protocols, I was not informed that these two features needed to be integrated into the incremental build mechanism. As a result, all the command-line related functionalities and the documentation I wrote at that time had to be deleted. I hope we can avoid situations like this as much as possible.

2. During the first few discussions about developing --check-links, it was never mentioned that it needed to be implemented and integrated as a subcommand under maintainer. This later required changes and migration for the previously implemented author --check-links functionality and documentation.

3. The requirement for a decentralized design was not mentioned earlier, which led to feature rewrites, including the removal of the whitelist mechanism in --check-links and the previous YAML configuration approach used in --program-check instead of markup annotations. This decentralization requirement had never been mentioned in the related documentation like course_testing.md or in any prior discussions before I started the development.

In your latest comment about Documentation readiness, you also mentioned the hope to reduce rework, which is exactly what I hope for as well.

[RYZENNAVI]

Updated maintainers.md

• I adjusted the overall structure of maintainers.md and added numbering to several sections.
• I rewrote paragraphs to match the style of authors.md to maintain stylistic consistency.
• Following the suggestion, I added Purpose and use cases and Prerequisites as new sections. I'm not certain whether this is acceptable.
• I supplemented the new --check-links content, e.g. added which parameters are supported and provided concrete notes for the current specific situation.
• The other part of maintainers.md (the check programs section) may also use the sedrila.yaml configuration in the future and may adopt an incremental-build approach. For example, in the current CI workflow, the process first runs sedrila author to build the course (which creates a ZIP file at /tmp/build_i/itree.zip), but this built ZIP file is not actually used by the program checker. Instead, the program checker handles altdir/itree.zip differently depending on whether it is a ZIP file or a directory. When running locally in the propra repository or in CI, it directly uses the existing altdir/itree.zip/ directory within the workspace for testing. Unpacking a ZIP file is currently only an alternative option. If incremental builds are introduced later, both of these existing approaches will be deprecated and removed.
• Therefore the current --test-programs and itree.zip-related text merely documents the existing implementation; it is expected to change substantially later.

[prechelt]

Feedback on your feedback

Regarding your "Feedback on the current situation" (#31 (comment)): It appears I have done wrong to you; in that case, I am sorry for that and thank you for your calm reaction.

Here is why I reacted so strongly:
The first sentence of the sedrila documentation states "A 'self-driven lab' (SeDriLa) course is one where students select freely a subset from a large set of tasks." and does not mention propra-inf at all.
The very effort of splitting the two repos would be most inconvenient if the two were meant to form a whole.

Obviously, propra-inf needs to know about sedrila, but information flow in the other direction should be limited as much as possible.

[prechelt]

Feedback on "My thoughts on the feedback" #31 (comment)

Reading your text, it appears to me you are making the following assumptions: (1) I should tell you exactly what to do and you will merely execute those instructions, (2) With some more effort, I would be able to provide flawless instructions.

Both of these are wrong, the first one is the important part.
The character of a master thesis is characterized in §9(1) SPO: "Die Masterarbeit soll zeigen, dass die Studentin oder der Student in der Lage ist, eine Fragestellung aus dem Gebiet der Informatik auf fortgeschrittenem wissenschaftlichen Niveau selbstständig zu bearbeiten".
The key term here is "selbständig".
So the division of labor is supposed to work as follows:

• I pose a problem (automated quality assurance of as many properties of the content of a SeDriLa course, specifically propra-inf, as possible), formulate a few preliminary ideas for illustration and as a starting point.
• You find and read pertinent literature, evaluate those ideas of mine, experiment with (possibly several) approaches for implementing them, extend the ideas, complement them with fresh ideas, experiment with those as well, ask for my feedback, and eventually present a consolidated implementation of those ideas that appear worthwhile and fit into the time budget of a master thesis.

If we learned anything from agile software development, than that rework is essentially unavoidable in such a situation, as the initial understanding of the requirements is too incomplete.
Please expect things to move on in a similar manner than what you have experienced so far. The better you manage to think through the suitability of your first implementation, the smaller the rework may become, but it is not going to go away.