gbadev-org / gbadoc Goto Github PK

1. Which (markup?) language should we use to write the documentation?
2. Which tool can we use to read the files written in (1) and render them in HTML?

We should disable the Wiki tab. Content shouldn't get into the repo wiki, it should be going into the repo files which are published to github pages. Having the wiki enabled can give people the wrong idea.

We should also consider enabling the Discussions tab. We have the discord, but that's only good for short term discussions. For longer term questions, it's nice to have a place to post about something and people potentially can see it days or weeks from now.

We should document the audio part from http://www.belogic.com/gba/ . Maybe ask the author about licensing that documents?

Related:

• rust-lang/mdBook#88
• void-linux/void-docs#416

HTML -> PDF via pandoc could be an alternative, too

Which license should we apply to the produced assets (figures and text)?

(insert inception noise here)

Questions

• Should the RFC process itself be documented? I think most importantly an issue template would be good so all the important information gets included from the get-go (checklist of questions, related/blocking RFCs, time estimate for resolution, so on), but also how and when we decide to resolve

• What should the editing, review and contribution process look like? I think Pull Requests are the way to go, since it lets us make use of GitHub's review features, and hopefully prevents merge disasters.

  • Should PRs always be done against a new branch, and disallow committing to the main branch directly?

This RFC marks the start of a community initiated effort in researching and documenting the GBA architecture. Our goal is to produce something similar to Game Boy's Pan Docs.

• Open Source/Public Domain (#3)
• Easily editable and improvable by anyone (Markdown, RST) (#2)
• Easily navigable/searchable HTML as primary final render target

Some basic points to decide on:

1. What's the objective of the project? Which parts of the GBA hw/sw should be covered in a first minimal subset of essential topics?
2. What is the target? Emulator developers or Homebrew developers?
3. How are we gonna prove the stated facts?
4. Should we use another document as baseline? (E.g. ask nocash to release GBATEK under a permissive license)

Any suggestion for the favicon?

Which document should we use as a baseline?

• CowBiteSpec *
• GBAtek

Keep in mind we'll also need a permission enabling us to reuse. Items marked with * are already released with a permissive license.

This was something discussed in the Discord yesterday, and there seemed to be a lot of differing opinions on it so I think it's good to decide on it ahead of time

What Naming Conventions (Registers, Functions, Hardware), Should We Use?

There's a couple options that were discussed

• Follow the "official" names, as used by GBAtek, libgba, etc.
• Create new names.
  • What should the focus be?
  • Can we ensure people who don't know the new names can find them using the old ones?
• Use anglicized names such as "Display Control", "Keypad Input", etc, and only use shortened names where brevity is required, i.e. links, or code.

Personally I don't have significant gripes with the official names, although there's a couple undescriptive names and misnomers.

Additionally, we would need to come up with new names for undocumented registers, although this can be decided on a case by case basis.