OpenAPITools / OpenAPITools/openapi-generator
[REQ] Improve readme in structure and content
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
Is your feature request related to a problem? Please describe.
The readme seems convoluted with a lot of information "noise". This includes:
- redirecting paragraphs (e.g. section 3.1)
- not directly project related information (Sponsors, Presentations, Contributors)
- redundancy (e.g. section 2 & 3.0.) and general structuring (TOC at 3rd position, relevant sections are 1, 3 & 7 )
On the other hand a list (or reference to) with the actual generators is missing. ( e.g. a link to https://openapi-generator.tech/docs/generators)
This makes ist hard for people with disabilities to grasp the project as a TOOL!
Describe the solution you'd like and alternatives
Restructure readme by moving the "noise" to dedicated files and link them directly from the TOC.
However I understand the need for the billboard style in a sponsored and voluntary ❤️ project.
Thus my alternative suggestion would be to move the actual installing and usage into a dedicated quick-start-manual-file. (e.g. by prominently linking to https://openapi-generator.tech/docs/installation or a readme within the docs folder)
Additional context
if you need a feel for how this looks to e.g. dyslexic people, then add a "the" after every other (or 3rd) word and subject the result to an automatic double translation (forward & backward).
It might not be exactly what I am experiencing reading that "readme" but it might give an idea.
Thank You for Your consideration
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the repository README and the linked docs/installation and generators pages to map the current sections, redundancies, and missing generator reference. Done means the README has a clearer structure for accessibility, with unrelated material moved or linked appropriately and installation, usage, and generator information easy to find.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100