Write a project design doc

mattxwang commented 3 years ago

One of the things I think Creative Labs does particularly well is writing a DESIGN_GUIDELINES document. They outline their tech stack, file/component structure, approaches to styling and modularizing and in general, how they make decisions. I think this piece of documentation - if it's updated - is invaluable for onboarding new members and making our project more contributor-friendly.

I propose we make a project design doc. We should discuss (with heavy inspiration from Creative Labs):

project principles
code style and format (with a callout to linting and auto-formatting)
our general tech stack
repository architecture / file structure (with a callout for file-based routing)
component design
styling (with a callout for SCSS and CSS modules)
utilities
assets
data

A tricky portion is that we are writing this after-the-fact, rather than driving a project with a set of design guidelines already in mind. However, this document can also be a goalpost for the direction of our project - in transitioning to React hooks, for example.

This will also be a team-driven effort, and I'd love to see someone else on the @uclaacm/dev-team champion this!

Related to #187; inspired by #198.

mattxwang commented 3 years ago

cc: @advaithg @evanzhong @BryanPan342

evanzhong commented 3 years ago

I really like the direction this is going.

Only thing that comes to mind right now is how to divide information between this page and our README and other documentation that (likely) will be proposed down the line.

From a quick scan I see CL also has a Contributing Guidelines doc. We talk about some of this content, in addition to how to setup a dev environment in our README.

BryanPan342 commented 3 years ago

Some insight into our doc decisions:

I personally hate absurdly long READMEs. IMO a README should give you just enough info to get started with a project
Our contributing guidelines is meant to help anyone (internal or external) in navigating how to make their first PR
Design Guidelines are a source of truth when it comes to reviews and consistency. If there are disagreements in styles, we will reference the design guidelines!

mattxwang commented 2 years ago

Wanted to bump this issue (@annaguo1012 and @advaithg) and also wanted to mention that Regina has been working on some great documentation for Teach LA's high-level goals + implementation strategy, and might be a good person to consult if she's free / can share the doc with you.

reginawang3495 commented 2 years ago

👀 👀 owo

I'd be down to chat/share the doc if it's helpful! TeachLA was also thinking of having a project plan doc and such if that's something y'alls would ever want to discuss

dtjanaka commented 2 years ago

i'd love to help work on this; were y'all also considering making a design doc a requirement for every issue/PR perhaps?

mattxwang commented 2 years ago

i'd love to help work on this

slide on in :)

were y'all also considering making a design doc a requirement for every issue/PR perhaps?

Hm, that's up to y'all - it probably depends on the scope of the issue, but at the end of the day this is all in your hands now - excited to see what happens!

annaguo1012 commented 2 years ago

Thanks for bumping this, Matt! I think it'd definitely be helpful to have this done before we start onboarding our new interns in the winter.

@reginawang3495 @dtjanaka thank you both for offering to help too hehe. Maybe we could set up a meeting sometime soon? (bearing our midterms schedule :,))

reginawang3495 commented 2 years ago

It’s more like I’m open to helping if needed :) I don’t necessarily need to be in the calls!!

matthewcn56 commented 2 years ago

More on this: starting last spring the dev team decided to have project outline documents that serve as living documentation so that when legacy projects get passed down from teams to teams, we can make the developer transition easier than ever. (linked template doc here!) (shout-out tla for starting the template i based this template off of)

It covers a lot of stuff for developers like above, but also has a couple things that are great for the overall vision of a project like what exactly does the project do, who's the Points of Contact for project purpose vs. design vs. tech, etc. and a link to it will be put inside of the CONTRIBUTING.md at the root of each project.

We're currently making one for the legacy projects and will def make one for the website as it's the project that gets passed down the most!

uclaacm / website

Write a project design doc #202