StarChart-Labs/flare-operations-plugins

[romeara]

I'd love some feedback on how to keep the documentation more clear and concise!

https://github.com/StarChart-Labs/flare-operations-plugins

Submitted by @romeara

[LappleApple]

Hi @romeara! I see lots of room for improvement here. :) Can you take a look at these and then maybe rework your README with these in mind?

• https://github.com/zalando/zalando-howto-open-source/blob/master/READMEtemplate.md
• https://github.com/zalando/zalando-howto-open-source/blob/master/producttemplate.md

[LappleApple]

@lhotari Do you want to take a look at these Gradle plugins?

[LappleApple]

Hi @romeara, will you go forward with the templates I shared? I will close this issue out, then if I hear from you with revisions/improvements we can reopen. Thanks!

[romeara]

Hi @LappleApple , thanks for the starting templates! I'm sorry it took so long to respond - I was away from a laptop for a couple weeks.

In general, an overall improvement I'd suggest is to reduce the amount of information recommended for the central doc/readme - even in the template, I was getting a little lost. One technique I've seen used is breaking certain pieces out into other files - GitHub has built-in integration for this sort of thing (ex: the CONTIBUTING.md file will result in a banner linking to it in pull requests)

My comparison between an attempt to use the template and the current layout resulted in the main information (what it does, general use and links to more verbose info, contribution, etc) being lost in a lot of extra info not as applicable to users or developers, so for now I'll continue tweaking from what we have.

That said, this project is an excellent idea - I can't wait to see documentation improving in projects thanks to your initiative.

I hope my feedback is helps, even if it's just in a "current community mindset" data sort of way :)