I'll try to cover several aspects of replies and what not here:
Folks should take my subjective/opinions with a grain of salt, i.e. they are worth as much as anyone elses. Do not consider my opinions somehow superior.
I agree that teaching material and reference material complement each other.
I do not want to see all the reference material turned into "docs for laymen" -- I actually thought I put this in my initial reply, but I didn't, it was in my 1st and 2nd write-ups which as stated I omitted for brevity.
I do not think the Wiki needs some kind of "massive revamp". Even if I did, it's not feasible to do anyway.
Sadly, this also proves my point about Wiki documentation in general -- in that the "bulk" of the initial work ends up rarely ever getting reorganised. In my experience this is true of almost every technical Wiki I've ever seen (subjective but true). In other words: unless it's well thought out from the beginning, it kinda never gets reorganised (again, subjective).
I do not think the Wiki is a lost cause, I just think the amount of effort to organise it now outweighs the original effort that was put in to create the content in the first place.
The
nestech.txt errata page has never bothered me -- if that is indeed the concern (re: "hurts the utility of that document by poisoning the well for people that might actually have gotten something good from it"). I think there may be concerns that I'd feel it was "a jab at me". I've always felt neutral-positive about it; that is to say, I think pointing out the mistakes is just as OK as fixing them. The latter is what I hoped the public would do when I made the document public domain with its final 2.00 release in 1999, but it never happened. If it happens now, great. If not, that's also OK.
Below is part of my 2nd attempt when originally posting in this thread, which should provide examples and my line of thought.
======
Do I have examples? Sure. Am I reluctant to post them? Yes, and I'll explain why at the end.
Look at anything on the "Programming guide" page. Note section "Getting started". Check out "Programming Basics". Why does this page exist? Seriously, look at the content. You don't try to teach someone about the 6502 CPU, then literally throw them subroutines of multiplication and division, followed by a "hello world" that references things that almost certainly won't mean anything to someone just learning 6502. There's even a brief set of code saying how to make a beep or continual tone -- except the user at this point has no idea about APU MMIO regs, and PROBABLY not even about audio at all: "period low? period high? I'm not on my period!" "Square? Yeah I've been called that before!" This page should be deleted and the subroutines stuck under "6502 code tricks/tips" or some other page, and the APU beep/tone trick placed somewhere else (keep reading).
So what do we have for basics? Well, there's a page called "CPU basics" under section "Tutorials". Sounds promising! Wait... this isn't a tutorial at all. It's absolute 100% reference material about the NES CPU on both a very low level (literal hardware) to a general level. Tutorial... right.
Still under "Tutorials":, we have "PPU reference" as the 2nd item. Reference != tutorial. Then "APU basics", 3rd on the list. NES audio is literally an advanced topic in every way/shape/form. This is subsequently followed by items like: CPU-level compression routines, mappers, then 6502 code tricks/tips, Limitations (I'll cover this in a moment), and then... Emulation Tutorials (I'll cover this in a moment too).
Also note the intermixing of terms here: "Tutorials" is the section, yet several of these things are references. Do people understand the difference between reference material and tutorials? rainwarrior and I seem to understand the difference, but hmm, maybe the fact others don't says something about "how" people read some technical documentation. Could that be the case? Ahem. Let's refocus:
So what should come after teaching 6502? Probably an item giving examples of "how" to do things on the NES, along with the realities of working on it, with some common techniques of things people might want to do. Math seems like a good idea, but still a bit advanced (IMO). Examples of realities to learn/understand first when developing on the NES: there is no printf() equivalent, so debugging is best left done in emulators for step-by-step code analysis. Accept the limitations of the machine, talk about what those are. Describe how to get something up visually on the screen which can be used as a printf() style debugging -- which leads me back to that APU beep subroutine. And that "Limitations" page.
About that page... check it out. Paraphrased, this is it: "the NES has some limits. Here's a list of game genres and technical complexities you'll run into in each one. Oh, and while I'm here, here's a section on Music". All of that -- huh?!?! We should be able to tell from the style, content, organisation, etc. who made this page. I see some people have edited it, but it was basically written in 2009 (see above: bulk gets written, rarely reorganised). Okay, so the content here is good and relevant *for that subject matter* -- why is the page called "Limitations"? Nebulous and inaccurate. "Game design limitations" is better... except for that Music section, which is what defeats my entire argument about the name of the page. (Right now IRL I've got both my fists in the air yelling "TEPPLES!!!", haha. :-) )
The above paragraph and page/example should, I hope, make my point about organisation, editing, etc. really clear. This is what I mean when I talk about pages being filled with "stuff" that are just like "?!" and aren't really classified or organised properly, especially when considering where that page is placed (Tutorials -> Limitations).
Okay, maybe I'm just being a crotchety old man, a pedant. More examples are required, right?
So let's switch to graphics for a moment, because that's a big part of what drives people to the NES these days.
The "PPU nametables" document literally describes nametables in 3 lines, combined with an ASCII diagram that has X,Y coordinates and lacks a legend (why are there X,Y coordinates anyway? To denote pixels? This is confusing because there isn't >256 or >240 offsets on the NES). Then suddenly, there's a "Background evaluation" section within that same page -- why? That has to do with PPU rendering, which has its own document/page.
The "PPU rendering" page is extremely helpful, but the presentation of information (all the way down to the ASCII diagram) is very confusing. It's like a wizard's tome. "This will make sense to you if you are familiar with it, else enjoy pulling your hair out." What's funny about this page is that at the bottom, there's the "PPU frame timing" image/SVG (very helpful), but also a link to a *separate* document called "PPU frame timing" that doesn't even have said image/SVG in it.
Then we have the "PPU pattern tables" page, which is tolerable... but maybe not, because it's one of the things the user in the thread that prompted *this* one had trouble understanding (pattern vs. name). The ASCII diagram shown is a modified rip-off of the one I did in nestech, and has a very bizarre layout that only makes sense if you understand what it's referencing. For example, it labels the strings
$0xx0=$41 01000001 as "Bit planes". What?! No.
$0xx0 is the PPU RAM location -- with a preceding 0 for pattern table 0, except that isn't even explained (or relevant!) to comprehending the data format -- followed by the hexdecimal value of the actual byte in RAM, followed by the binary rendition of that (omitting the
% that makes it obvious). It then ties all these together to represent the colour values of 0-3 (with
. (0) meaning transparent (this is good!), just like nestech), through equals signs at the bottom and top of the subsequent PPU RAM bytes that make up a tile that the user can't even comprehend the shape of (what is that tile anyway? It looks almost like a botched swastika) -- why was this shape chosen rather than something almost everyone would recognise? Compare that page to nestech please, verbatim (in the late 90s we tended to use the term "VRAM" to refer to PPU RAM):
Code: Select all
D. Pattern Tables
-----------------
The Pattern Table contains the actual 8x8 tiles which the Name Table
refers to. It also holds the lower two (2) bits of the 4-bit colour
matrix needed to access all 16 colours of the NES palette. Example:
VRAM Contents of Colour
Addr Pattern Table Result
------ --------------- --------
$0000: %00010000 = $10 --+ ...1.... Periods are used to
.. %00000000 = $00 | ..2.2... represent colour 0.
.. %01000100 = $44 | .3...3.. Numbers represent
.. %00000000 = $00 +-- Bit 0 2.....2. the actual palette
.. %11111110 = $FE | 1111111. colour #.
.. %00000000 = $00 | 2.....2.
.. %10000010 = $82 | 3.....3.
$0007: %00000000 = $00 --+ ........
$0008: %00000000 = $00 --+
.. %00101000 = $28 |
.. %01000100 = $44 |
.. %10000010 = $82 +-- Bit 1
.. %00000000 = $00 |
.. %10000010 = $82 |
.. %10000010 = $82 |
$000F: %00000000 = $00 --+
The result of the above Pattern Table is the character 'A', as shown
in the "Colour Result" section in the upper right.
The "PPU attribute table" page almost immediately throws the user a line of code -- helpful for emulator authors, not helpful for newbies, but also not useful as "reference material" either. The large ASCII depiction at the top (which I am known for doing a lot of myself, just not in that style -- when drawing ASCII boxes it's best to not use extraneous whitespace in ASCII boxes if possible), is almost in contrast to the subsequent images in the "Worked example" section. So here we have ASCII vs. imagery. Furthermore, the imagery in "Worked example" is actually misleading: here we have an actual nametable shown/drawn in its entirety, except using PPU RAM offsets of the attribute table. It's trying to describe, on-screen, what the attribute table is affecting -- this is in no way/shape/form obvious from the pictures. The ONLY PLACE that makes it clear is the TINY TEXT BELOW THE IMAGES. *sigh*
I will say though, one of the best PPU-oriented pages we have on the Wiki is the Mirroring page. I also "kinda" like the "PPU scrolling" page, but only select parts of it -- the bulk of it is insanely complicated and badly organised (use of separate linkable sections makes this page ugly and hard to follow). It's the more clear version of loopy's skinny.txt, i.e. it's better, except it's still not really clear (and it still remains unclear to most people, I think. It did then too, but it's critical to how the NES PPU works).
With regards to that page though, what's *really* needed for homebrewers in particular, is a "this is what you need to do" page/thing. Best practises and why. A big one would be the whole 2000/2005/2006 situation and why zeroing 2005/2006 at the end of NMI can alleviate graphical oddities (I'm speaking of the general-use case here, not complex situations).
Back to earlier stuff: how about that emulation-oriented page, "Emulation Tutorials?"
The page itself is actually sparse of information, because all it does is contain references to *other* pages (remember what I said about organisation of information being in one place?). It's an important page, but it has no substance. It's like a middle manager. I REALLY expected to see it reference something I have posted
time and time again: that
adc/sbc is the #1 badly-emulated instruction pair on the 6502 because folks don't understand two's complement (this wasn't taught in any CS class I took either). Understanding the overflow flag is actually hard, but important, given
bvc/bvs. There's no other truly useful emulator-focused information on this page. Maybe we should reference real-world situations people are encountering (see: forum).
Can I fix that up? Absolutely. Will I? Probably, when I feel like doing so (maybe this weekend). We currently have
146 known NES emulators in development, so it seems like we could relieve some of the repeated forum posts here by having better Wiki content. We get a lot more emulation-oriented posts than I think people realise (vs. general chit-chat about a subject, or vs. homebrew discussions). Banshaku's recent posts asking good questions are great because they get back to the roots of the forum, I think.
As for why I was reluctant to post examples:
Because the immediate rebuttal is always "in the time you wrote up these diatribe replies on nesdev forum criticising the Wiki, you could have simply improved the Wiki" -- which makes me want to reply with an expletive. These are key/critical pages, and my experience with Wiki editing historically has shown that when "revamping" something, people suddenly come out of the woodwork to complain about what you've done, resulting in reverts. In other words: it's actually easier for me to
not change any of the pages in risk of upsetting people. I've dealt with this here, as well as on other wikis (Wikipedia, EVE-related wikis, etc.). Nobody wants ripples in the water. So by even saying "this stuff is unorganised" I'm putting ripples in the water -- that nobody wants. Hard to have a discussion about it then, isn't it?
Possibly a better solution for all of this would be to actually have a proper area in the Wiki for starting out (both homebrew, and emulators -- separate sections). You want to know who's pretty good at teaching the "learning the NES" basics? Kasumi (
current example thread). I'm not half bad at it myself, but I tend to not hand-hold as much as Kasumi (I'm more of the "if you can't understand the concept that a register holds an 8-bit value, similar to a variable in a programming language, then you should give up" type :-) ).
======
Finally I want to answer one question posed: "Who reads nestech.txt and why?"
What's funny about the question is that it's almost the same question JoeGtake2 asked me when he interviewed me for The New 8-bit Heroes documentary: "why did you write your NES documentation, slash, who was it for?" So in a way I feel like I'm answering this question over and over throughout my life. I've always thought it was obvious, given the style and content, but I'll answer it just like I did for Joe:
It was originally intended for two audiences: 1) emulator authors and 2) homebrewers using emulators (because virtually no one had devcarts then. Yes, much to the surprise of youths, emulators are actually what prompted most of the NES homebrew movement. I only know of 4 people PRIOR to emulation that were doing NES reverse engineering: Alex Krasivsky (Landy), Marat Fayzullin (RST38h), Mark Knibbs, and Kevtris (I think)).
nestech.txt INTENTIONALLY did not go over the 6502 because there are tons of books and resources on those subjects already -- the NES CPU is normal every way barring lack of decimal mode and having an on-die APU. It INTENTIONALLY did not go over mappers because Firebug and others were already doing that (i.e. do not duplicate efforts). It INTENTIONALLY did not go over audio because audio is not a subject I myself understand well (and shortly after, folks like Brad Taylor went over this subject in greater detail, i.e. do not duplicate efforts). Edit: well, I guess it wasn't INTENTIONAL that I didn't go over audio -- you can see in the past (earlier than 2.00) I tried and failed miserably, which was not helpful for others. Quoting my own doc:
Code: Select all
+---------+
| 5. pAPU |
+---------+
To be written. Prior information was inaccurate or incorrect. No one
has 100% accurate sound information at this time. This section will
be completed when someone decides to reverse engineer the pAPU section
of the NES, and provide me with information (or a reference to infor-
mation).
But like I said, audio docs came out by Brad Taylor and some others some time after, so I think in the end things got covered. But it's true to this day that audio is a subject I do not grasp well.
It was, in essence, a document allowing someone to learn the aspects of the system to get started either writing games for it, or making an emulator for it -- and being able to comprehend the aspects of the system (esp. the PPU). And, not to brag, but it succeeded. NESticle was done from it (and Icer Addis gave me some info along the way as well) as were a few other emulators. It wasn't until loopy's skinny.txt came along, which revolutionised everything. And here we are today.
If there's one thing I've learned writing technical documentation it's this: if you write documentation for the demographic I
earlier called "semi-technical + unfamiliar", then the highly technical (whether familiar or not) will ALSO understand it. If you write documentation for the technically elite, the bar is set too high. Being a good technical writer involves knowing understanding the material yourself and then presenting it in a way that makes sense to the majority of people. It's a balancing act. You CAN write documentation in such a way that works for both... because that's what I've done publicly twice, and at companies as a subset of my job. I dunno what else there is to say about it.