Takeoff Readme

[tanepiper]

I've been trying to make the documentation for my project clear but would appreciate some feedback (especially as someone commented the Readme wasn't good enough

https://github.com/takeoff-env/takeoff is the main repo (which also drives the documentation on https://takeoff.sh via github pages, but the Readme is the index and the "hook" for people). This is the main tool I'm publishing.

It also ships with blueprints which include their own documentation and the default blueprint is here https://github.com/takeoff-env/takeoff-blueprint-basic

[LappleApple]

Thank you for the submission, @tanepiper. Will get to this ASAP, if no one else does. :)

[tanepiper]

@LappleApple Hello there! I was wondering if anyone was going to get around to this?

I've completely re-written the Readme! Taking some lessons from work I tried to write clearer docs. Any feedback would be welcome, including any spelling mistakes that probably slipped through :)

[LappleApple]

Heya, took a look and have these suggestions:

• It's great that you have a "Why" section—place that at the top so readers can find it right away. Your blog post under "References" is clearly/well written and answers a lot of important questions about your project -- I would lift text from it and adapt for your "why" section.
• More on the Why section: Are there other tools available that are similar? Tell us why your project is different from them -- what advantages does it offer? Are there specific use cases for which your project is the best?
• Include the bullet points from your blog post in a "Features" section near the top of the Readme so people can quickly identify if your tool is right for their need.
• Do you have any success stories, either your own or from others? I'd either include 1-2 lines about them in the Readme, likely in the "Why" section, or spin up an Adopters.md file and list users there along with their success stories (again, 1-2 lines, and if you're an adopter it's ok to list yourself). An Adopters file 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. Right now it's eating up a lot of Readme real estate, and without a Table of Contents it's hard to digest. So I'd put these instructions in their own file and link to them from the Readme.
• You might mention your "docs" folder and highlight what folks will find there (one sentence or part of a sentence).
• Add a "Troubleshooting" guide and link to that from your Readme--don't post it as a section there. :)
• Is adding more contributors a priority? If so, add a governance.md describing different contributor roles you might 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.
• Do you have a 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.

Let me know if this is helpful.

[LappleApple]

Closing this issue as I provided a response. Feel free to reopen if necessary. :)