search

omshub / website

Unofficial reviews site for Georgia Tech's Online Master of Science (OMS) programs. Contact: gt.omshub@gmail.com
https://omshub.org
GNU General Public License v3.0
57 stars 10 forks source link

[DOCUMENTATION] New user guide #39

Open awpala opened 2 years ago

awpala commented 2 years ago

Add a markdown file describing the general overview of the app & architecture, how to run locally, etc. May involve pulling some information out of / trimming down the general README

knakamura13 commented 2 years ago

What is the current README missing that you would suggest we add to this "new user guide?" For example, it already has instructions for how to run locally and it's fairly trimmed down at the moment.

awpala commented 2 years ago

I put this as a placeholder thought, but may or may not necessary depending on how the README evolves. The main idea I want to document here (once the ideas are established concretely) is where all external services are located and how to access them (e.g., Vercel, [TBD backend system], Chromatic, etc.), which might overclutter the README at some point and warrant its own separate thing. Time will tell!

disposedtrolley commented 2 years ago

where all external services are located and how to access them (e.g., Vercel, [TBD backend system], Chromatic, etc.), which might overclutter the README at some point and warrant its own separate thing

This could tie in with the artefacts produced from https://github.com/omshub/website/issues/40

Something else we could adopt to improve the new user experience is the normalised script pattern. It's essentially a set of bash scripts that bundle up the commands you normally see in a README into consistently named files. The .devcontainer fast path we have might alleviate the need for this, but it's nice to have non-Dockerised scripts that people can run if they want to. It'll also be useful if/when we have more repos.