Vastly improve the documentation

This includes more clear explanations, images, etc.

Signed-off-by: Miquel Sabaté Solà <mikisabate@gmail.com>

1 files changed, 23 insertions, 27 deletions

diff --git a/README.md b/README.md
index df49e70..d239e28 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,16 @@
-<p align="center">
-  <a href="https://github.com/mssola/NES/actions?query=workflow%3ACI" title="CI status for the main branch"><img src="https://github.com/mssola/NES/workflows/CI/badge.svg" alt="Build Status for main branch" /></a>
-</p>
+Examples for the Famicom/NES. These examples are not full blown games nor
+standalone projects. Rather, they should be seen as learning material and
+experiments. If you want to check out standalone projects that I have written,
+check out [this list](#other-projects).
 
----
+## Build
 
-This repository consists of some examples of programs for the NES. You can build
-them by just calling `make` and they will then be available at the `out`
-directory. Before doing that, though, you will need a compiler for the 6052
-platform. A good option is [cc65](https://github.com/cc65/cc65), which is
-available on all major platforms. Otherwise, if you want to use another
-compiler, you can pass the `CC65` and `CCOPTS` variables to the Makefile.
+You can build everything by just calling `make` and binaries will then be
+available in the `out` directory. Before doing that, though, you will need a
+compiler for the 6052 platform. A good option is
+[cc65](https://github.com/cc65/cc65), which is available on all major platforms.
+Otherwise, if you want to use another compiler, you can pass the `CC65` and
+`CCOPTS` variables to the Makefile.
 
 After that, it's recommended that you run the ROMs with an emulator with
 debugging support or at least some form of memory visualization. This is because
@@ -19,33 +20,28 @@ NES memory. A safe bet is to go with either
 [Mesen](https://github.com/SourMesen/Mesen2/), which provide tools like RAM
 watchers or a full debugger.
 
-Notice also that I will use some terms without actually introducing them. That
-is, I expect you to go over the [NES Dev
-wiki](https://www.nesdev.org/wiki/Nesdev_Wiki) for glossary or for full
-documentation on the stuff being shown here. For example, if I am writing an
-example code using the UNROM or the MMC1 chips, I assume that you will go over
-the [NES Dev wiki](https://www.nesdev.org/wiki/Nesdev_Wiki) for details on what
-these chips actually are or how they were used. That is, if you find that on a
-bunch of comments I write stuff like "memory mapper", "MMC3 chip", "OAM" or
-stuff like that, just go to the [NES Dev
-wiki](https://www.nesdev.org/wiki/Nesdev_Wiki) to get a better picture.
+## Examples
 
 The examples are distributed like this:
 
 - `basics`: simple examples which cover basic stuff for NES development. These
   examples are self-contained and supposed to be read by absolute newcomers. The
-  description for each example is covered by an initial comment on each file.
+  description for each example is covered by an initial comment on each file,
+  and you can also find more info in the [basics/README.md](./basics/README.md)
+  file.
 - `space`: example in which you can move a spaceship with subpixel movement and
-  shoot bullets. Consider this an evolution from the `basics/sprite.s` example.
-  That is, we are no longer just showing a sprite, but we make it move and
-  perform an action like shooting bullets.
+  shoot bullets. Consider this an evolution from the `basics/sprite.s` and
+  `basics/input.s` examples. That is, we are no longer just showing a sprite,
+  but we make it move and perform an action like shooting bullets.
 - `scroll`: different scrolling tactics. Read the
   [scroll/README.md](./scroll/README.md) file for more info.
 - `fx`: miscellanous effects that can be achieved with this humble machine.
 
-Other than that, I have also written complete games. Take a look at
-[jetpac.nes](https://github.com/mssola/jetpac.nes), which is simple enough so a
-newcomer can read it, but complex enough so it's an actual game.
+## Other projects
+
+- Full games: [jetpac.nes](https://github.com/mssola/jetpac.nes).
+- Libraries: [list.nes](https://github.com/mssola/list.nes).
+- Misc: [Advent of Code 2023](https://github.com/mssola/aoc2023.nes).
 
 ## License