Document design decisions under docs/

[yamanidev]

Is your feature request related to a problem? Please describe.
There is currently no centralized place to track the design decisions made throughout the project. This makes it difficult for new contributors or team members to understand the reasoning behind certain choices.

Describe the solution you'd like
Document the design decisions made during the development of the project in a docs/ folder. This will serve as a reference to understand why specific design choices were made and help maintain consistency across the project.

Additional context
An example of how the documentation could look like is Epic Stack's.

[omdxp]

What about the discussions page?

[yamanidev]

That could be helpful as an addition, but having a single source of truth for the existing design decisions made, I think it would be best if they're documented separately under docs/ for example.

What do you think?

[omdxp]

I like this idea, having a single source of truth is always good and it would help new comers what the project went through and how it reached this point, wdyt @ZibanPirate ?

[ZibanPirate]

i like the idea, i'm fine with this as long as we have a single file that documents everything

i'm against having multiple files, one per decision

[ZibanPirate]

now that I think about it, it may make sense to document these decisions in the ./CONTRIBUTING.md file, since it is used by GitHub to guide contributors

[yamanidev]

I don't think so. CONTRIBUTING.md is usually guidelines on how to contribute, about certain conventions and whatnot, not the technical decisions that were made for the given project.

wdyt?

[ZibanPirate]

My understanding is: the idea of "documenting decisions" did not exist out of vacuum, but instead we need it to "help contributing to the repo", and if that is the reason, then it makes sense to be in the CONTRIBUTING.md file (which GitHub uses as part of their contribution UX)

Or are there other reasons (that interest us) for documenting decisions?

[yamanidev]

It's definitely the case, it's only relevant for someone who's interested in the project and especially contributing to it, I just have trouble imagining myself checking the CONTRIBUTIONS.md file for this kind of information, it doesn't sound intuitive.

For a start, I don't think it would matter where we put this information, we could always explicitly point it out in the README.md that it's in the CONTRIBUTIONS.md file, and then if this becomes troublesome to manage later, we could discuss it again.