Current Situation
Compared to the other repositories of the Eclipse Basyx project, our top-level README.md looks empty and not as visually appealing. Alternative examples can be found in:
- The GO SDK
- Very clear structure, good overview
- The AAS Web UI
- Summarising status badges
- However, the emojis should not be adopted, as they appear unprofessional and AI-generated when used excessively
Furthermore, we currently link to the PyPI, but not the Conda release.
|
These are the implemented AAS specifications of the [current SDK release](https://github.com/eclipse-basyx/basyx-python-sdk/releases/latest), which can be also found on [PyPI](https://pypi.org/project/basyx-python-sdk/): |
Proposed Change
The top-level README.md should be revised. Personally, I like the GO SDK's approach; we could ask them if we are allowed to adapt or improve it. Possible adaptations could include:
- More, better structured subsections
- Introductory section
- Table of Contents
- Project Overview
- Architecture Overview
- Setup & Installation
- ... (GO SDK)
- Further Reading
- The BaSyx Python SDK logo in the introductory section
- Badges summarising the status of the repository
- Admonitions for highlighting
- A short introductory video, similar to the old Java SDK
- An FAQ
- An additional link to the Conda release
- ...
I know that more in-depth information is provided in the subrepository-specific READMEs, but we should still add a few more examples to the top-level README, as this is the first (and maybe last) piece of documentation that most users will see.
Current Situation
Compared to the other repositories of the Eclipse Basyx project, our top-level
README.mdlooks empty and not as visually appealing. Alternative examples can be found in:Furthermore, we currently link to the PyPI, but not the Conda release.
basyx-python-sdk/README.md
Line 8 in bdbfdcc
Proposed Change
The top-level
README.mdshould be revised. Personally, I like the GO SDK's approach; we could ask them if we are allowed to adapt or improve it. Possible adaptations could include:I know that more in-depth information is provided in the subrepository-specific
READMEs, but we should still add a few more examples to the top-levelREADME, as this is the first (and maybe last) piece of documentation that most users will see.