Write a project design doc

[mattxwang]

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]

cc: @advaithg @evanzhong @BryanPan342

[evanzhong]

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]

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]

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]

👀 👀 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]

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]

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]

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]

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

[matthewcn56]

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!