realworld
realworld copied to clipboard
gothinkster
Standardize README's for completed repos
For someone who is landing on an example repo and has no idea what RealWorld is, I'd imagine they'd be thinking "uh, wtf is this". For example, the backend codebases don't mention how to get an example frontend setup & running (much less where you can choose a frontend at all). This could easily be fixed with a standard "what is this"-esque section at the top of every README.
Further, would be great to have standard sections on common topics like "Installing Dependencies", "Running the Application", "Architecture Overview", etc that people will typically be looking for. Definitely a key improvement for the UX of perusing/exploring repo's.
Would love thoughts on this!
@EricSimons Great idea. I think this is a must. Having a clear guideline for the README would be very helpful to users who land on the repo's directly. I tried to squeeze in as much info as possible in the laravel repo and i still feel its lacking. Having mandated information on different topics will keep force repo owners to maintain proper guidelines and instructions for its users, making it easier for them to get it up and working with ease.
Has any progress been made on this? I can't think of any reason to not make this a thing.
I think this would be great as well. Here's my rough attempt. Maybe this could be a starting point and we can iterate on this until we nail down what everyone likes?
Required:
Default Header
This includes the logo, demo and realworld links and quick overview/introduction.
Prerequisites and Dependencies
Should include setup instructions for any languages, tools, or environment settings required to run the application. It would be a bonus to have instructions for different platforms if that is an issue.
Port Management
Should list what ports are required for what and how to change the port(s) if there is a conflict.
How to Run the Application
Should include step by step instructions on how to execute the application.
How to Manually Test the Application
Should describe how to test the application manually (Postman and Swagger for backends, browser for front ends, etc.)
How to Run Automated Tests
Should describe how to run any unit tests, how to use newman with Postman to run Postman scripts.
Links and Resources
Should reference the documentation for any libraries being used, relevant blog posts and tutorials, etc.
Optional
Code Overview
Library/Framework specific notes. Folder structure, explanation of decisions being made, why something is a best practice if that's the case, etc.
Deployment Instructions
Give instructions for how to deploy it somewhere, Heroku, Digital Ocean, AWS, etc.
Thanks
Show some love to anyone that helped.
@Cameron-C-Chapman ^ that covers everything that I was thinking (& more!) — thanks a ton for putting this together!
Does anyone have any other ideas/thoughts here? I'm planning on migrating a few of the readme's over to this format and see how it looks 👍
My only recommendation would be turning this checklist into a template. Use text like (Insert prerequisites and dependencies here.) to make sure whoever is writing the doc puts everything in the right place.
^ dope. I'm gonna add this to the new checklist that will be included with the starter repo!