change the engineers diary to markdown, add to git/website

[rpietzsch]

No description provided.

[rpietzsch]

The diaries shall be managed in individual repositories dedicated to the engineering artifacts (CAD, circuit specs, etc.).
There those shall be managed as markdown files.
The idea is to integrate / link the same from the website:

• integrate the (rendered) markdown file(s)
• generate a consolidated PDF through CI/CD in each respective (CAD) repo and link to the pipeline PDF artifact
• other ideas welcome …

[florian-rabis]

Yes, however, these repositories are dependent on each other. It is therefore necessary to establish a connection between the respective repositories.

Documentation must not be done independently of development. I believe that Git branching should be used here. Perhaps in this manner:

If a new feature is developed based on a release on main, it must, of course, be tested and documented. However, nothing undocumented should ever end up on main.

main ______________________________________________________________________________>
development       \__________                                 /
testing                      \_____________                  /
doc                                        \________________/

[florian-rabis]

I think repositories should not be divided based on the type of data but rather based on their reusability and function. In other words, they should be considered as semantic units.

Pure software has no geometric characteristics. Therefore, if software can run on multiple different architectures or systems, it can be outsourced into separate repositories.

However, electronics can have properties of both software and mechanics in terms of their geometry and can thus be closely tied to the overall device.

So, if the electronics change over time to the extent that they no longer fit geometrically into the designated places in the actual device, this in turn leads to geometric changes in, for example, the housing, etc.

But fundamentally, I also believe that as much as possible should be outsourced into separate repositories and treated as packages, just as one would do with the package managers of a distribution.

In the long run, however, managing this manually is not practical. This is precisely why an OSH package manager is needed—to easily add components to one's project with a single click or to outsource individual parts into such a system at a certain point in time.

Something like this:
You mark a folder or a CAD file, etc., and with one click, it is outsourced into a new repository. In the process, a number of fundamental files are automatically created, such as README.md, LICENSE.md, okh.toml, and a standard folder structure, as well as a basic description wherever possible. This new repository is then immediately reintegrated into the original project.

[florian-rabis]

But I see this is a different topic. We should discuss this in a separate issue.

Regarding the documentation as Markdown files, I absolutely agree.