Feedback for README.md of MapStruct
gunnarmorling opened this issue · 4 comments
Hi, I just learned about this project/service -- it's a fantastic idea!
If you have the time, we'd love to have your feedback on the README of MapStruct: https://github.com/mapstruct/mapstruct. We spent quite some time on it originally, but since then it has aged a bit and I think there are a few opportunties for improvement. Any thoughts and input on that would be very much appreciated.
Thanks, @gunnarmorling. Will look ASAP!
Heya, looks like ASAP (see my last comment) = +5 years...
Took a look and have these suggestions:
- Your "what is MapStruct?" section is pretty good. Have you thought about creating an "Adopters" file where you list users and highlight the benefits they've gotten from using the project? Doing this can be useful for growing your user community and reinforcing the value and magic that this project offers.
- Make sure your install/build/test/run documentation is as thorough as possible--consider running through it with a friend who's using it for the first time, and note where they get stuck. Then fix.
- Shove all of that step-by-step into its own .md file and include the link in your Readme, to let readers know it's there.
- Add a "Troubleshooting" guide and link to that from your Readme--don't post it as a section there. :)
- Add a governance.md describing different contributor roles you offer (users, contributors, maintainers) and what their responsibilities are; how to propose feature requests; how you make decisions; and how you decide to change your governance policies.
- Where is your roadmap? Add a dedicated roadmap.md file and link to it from the Readme. This will show contributors what your plans are, where the project is headed.
- Highlight your Contributing.md on the Readme so contributors see that you have one and can learn right away how to help.
- No need to post the licensing section at the bottom -- you have the dedicated file there already.
Let me know if this is helpful.
Closing this issue as I provided a response. Feel free to reopen if necessary. :)
Thank you so much, @LappleApple! Hey @filiphr, there might be some inspiration here for improving the MapStruct README?