Skip to content

Modernise top-level README.md #475

@moritzsommer

Description

@moritzsommer

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgeneralSomething to do with the BaSyx Python SDK repository in general

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions