search

gbdev / rgbds

Rednex Game Boy Development System - An assembly toolchain for the Nintendo Game Boy and Game Boy Color
https://rgbds.gbdev.io
MIT License
1.36k stars 172 forks source link

Write technical documentation #707

Open ISSOtm opened 3 years ago

ISSOtm commented 3 years ago

A large part, I believe, of why RGBDS maintainership is not user-friendly, is the lack of technical documentation. The codebase has a lot of implied conventions, organization, and behavior, which are definitely not clear at first glance.

Questions:

For the organization, I think explaining the build systems (and why there are two) as well as the tree hierarchy should be fairly low-hanging but nonetheless useful fruit. I think we should also document some decisions that were taken, and their rationale. Currently, those were decided largely on Discord, and some in GitHub issues, but neither is a good archive, especially the former.

For the location, I think a dedicated folder on our website should do the trick. I wouldn't make it a sub-folder of /docs/, though, but a dedicated folder.

Rangi42 commented 8 months ago

An ARCHITECTURE.md document explaining at a high level how each program is structured, would probably be very helpful for new contributors who don't know where to start.

ISSOtm commented 3 months ago

I found this useful reading: https://matklad.github.io/2024/03/22/basic-things.html