-
Notifications
You must be signed in to change notification settings - Fork 7.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Standardize README's for completed repos #103
Comments
@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 HeaderThis includes the logo, demo and realworld links and quick overview/introduction. Prerequisites and DependenciesShould 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 ManagementShould list what ports are required for what and how to change the port(s) if there is a conflict. How to Run the ApplicationShould include step by step instructions on how to execute the application. How to Manually Test the ApplicationShould describe how to test the application manually (Postman and Swagger for backends, browser for front ends, etc.) How to Run Automated TestsShould describe how to run any unit tests, how to use newman with Postman to run Postman scripts. Links and ResourcesShould reference the documentation for any libraries being used, relevant blog posts and tutorials, etc. OptionalCode OverviewLibrary/Framework specific notes. Folder structure, explanation of decisions being made, why something is a best practice if that's the case, etc. Deployment InstructionsGive instructions for how to deploy it somewhere, Heroku, Digital Ocean, AWS, etc. ThanksShow 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 |
^ dope. I'm gonna add this to the new checklist that will be included with the starter repo! |
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!
The text was updated successfully, but these errors were encountered: