Develop a concept for the software development of all partners

[christoph-maurer]

Most partners of the joint research project and of the associated partners develop software. How can we do this best? What can we share with the partners to facilitate working together?

[simon-wacker]

If they need to understand the code that we have written, then it would be good if there was

• more documentation at different levels of abstraction (graphical user interface, software architecture, software building blocks, code documentation);
• diagrams to aid in understanding the textual documentation;
• tests (from integration tests to unit tests);
• examples;
• open communication (preferably on GitHub through Issues or Discussions).

And the same is true for code that they write and we need to understand.

[christoph-maurer]

• We need reproducible environments to compile code from others.

[simon-wacker]

Addition: To develop different parts of one piece of software, the communication protocol at the level of abstraction at which communication shall take place needs to be agreed upon in advance as precisely as possible without hindering progressive changes and the actual implementation. The level of abstraction can for example be a web API for communication over the WWW, a program API like an interface definition for usage within the same high-level programming language, command-line definition for CLI usage, ... There needs to be a common understanding and a well-enough agreed upon protocol to start implementing. If the implementation requires changes though they should be easy to do (it is hard to foresee everything in advance). I believe that writing a specification ("Pflichten-/Lastenheft") and implementing it should go hand-in-hand (this is what agile development is).

[christoph-maurer]

• more documentation at different levels of abstraction (graphical user interface, software architecture, software building blocks, code documentation);
• diagrams to aid in understanding the textual documentation;

@simon-wacker Shall we use https://ivangoncharov.github.io/graphql-voyager/ for the documentation of the apis?

[christoph-maurer]

@christoph-maurer

• Improve README with diagrams from PlantUML
• Improve description of /examples/

[simon-wacker]

Regarding GraphQL voyager: Yes, let's use it. Simply by adding the link https://ivangoncharov.github.io/graphql-voyager/?url=https://www.buildingenvelopedata.org/graphql/ to the Readme and maybe also to the website itself. I tried to add GraphQL voyager itself to our website to make it accessible under https://www.buildingenvelopedata.org/graphql-voyager/ but I faced some issues that I couldn't fix quickly. So, let's just use https://ivangoncharov.github.io/graphql-voyager/?url=https://www.buildingenvelopedata.org/graphql/

[christoph-maurer]

Awesome! Thanks a lot!

[christoph-maurer]

The link https://ivangoncharov.github.io/graphql-voyager/?url=https://www.buildingenvelopedata.org/graphql/ doesn't work anymore.

But the links https://graphql-kit.com/graphql-voyager/?url=https://www.buildingenvelopedata.org/graphql/ and https://graphql-kit.com/graphql-voyager/?url=https://www.solarbuildingenvelopes.com/graphql/ work.