rgbds
rgbds copied to clipboard
gbdev
Write technical documentation
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:
- [ ] What to put in there? (Organization)
- [ ] Where to put it?
- [ ] Do we want to archive old versions'?
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.
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.
I found this useful reading: https://matklad.github.io/2024/03/22/basic-things.html
It would be really helpful for any future post-1.0.0 maintainers if they could read ARCHITECTURE.md and get at least a basic high-level overview of how RGBASM and RGBLINK work. (RGBGFX is relatively simple apart from the works of its palette-generation algorithm, and RGBFIX is definitely simple.)