Develop a concept for the software development of all partners

building-envelope-data / api

API specification to exchange data about building envelopes

MIT License

3 stars 1 forks source link

Develop a concept for the software development of all partners #290

Open christoph-maurer opened 1 year ago

christoph-maurer commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

[ ] We need reproducible environments to compile code from others.

simon-wacker commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

@christoph-maurer

[ ] Improve README with diagrams from PlantUML
[ ] Improve description of /examples/

simon-wacker commented 1 year ago

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 commented 1 year ago

Awesome! Thanks a lot!

christoph-maurer commented 1 year ago

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.