I spent about 30 minutes writing up a reply on this subject. After going back to proofread it, and thinking about it a bit more deeply, I saved what I had to a text file (if anyone wanted it), then cleared the form contents. This prompted me to think about what it is I really wanted to say. I then wrote up another reply, which took about another 45 minutes, and included actual problems in the Wiki with references. I went back and proofread it, and stepped away to think about it. I decided it too would be pointless, so I saved that to another text file and cleared the form contents once more. I wanted to really convey, concisely and summarily, what my concerns were -- because nobody these days reads more than a few paragraphs at most. So here's my 3rd attempt:
The Wiki in its current state tends to work well for people who already have familiarity with the system, or who are what I would call "savants" or may have some past experience with classic console systems. There are some pages that are friendly to both "newbies" as well as experienced folks, and that's good, but most are not. This is always going to be subjective, there is no way around it. But if you feel they are good, legible, clear, and convey the information about the NES's pattern table + nametables + attribute tables in a concise manner that makes it easy for a newcomer to understand, then just look at the thread in question and ask yourself how the user misunderstood it the way they did. It's not just limited to PT/NT/AT though.
The Wiki suffers from the same problems every technical Wiki I've seen has suffered from: lack of organisation, amplified by information scattered all over the place; the Super Famicom Development Wiki is almost the exact same way. These types of Wikis often start as "document repositories" (and that's true in both cases), which then get edited by someone initially, then over time, neglected. Information often ends up being duplicated (page X says one thing, page Y says the same thing but slightly tweaked, forcing the user to look at History to see what was edited when, and hope that newer is better). Additionally, people start "splitting up" information into separate documents/pages, feeling this adds to the organisational aspect; in my experience it often doesn't (but when it does, it REALLY makes a big/positive difference). The trick is knowing when. Here's a point worth pondering: ask yourself why technical data on, say, an ASIC (example
) comes in a single PDF file, not 20 PDF files. This is something I learned from my SNES documentation days (where I had 1 file per subject/thing) -- people strongly preferred a single document.
If you're a homebrewer starting out, the information will "sort of" get you started, but you will end up posting on the forum (see: JoeGtake2's quest to make his own NES game). If you're an emulator author starting out, many of these pages (not all, but many, especially key/critical ones) are badly written and will not help you -- you are forced to dig through them all, this mass scattering of information.
I've written technical documentation personally and professionally for over 20 years, so maybe I'm biased. I don't know if I'm actually good
at it; all I know is I've been told at every job I've worked at that I write great documentation, and still to this day get Email about both my SNES and NES docs (mainly thank yous, I guess because they act as good initial stepping stones? I've never asked. I just say "You're welcome!").
Writing documentation takes up TONS of time. Programmers in particular HATE it (I'm one of those weird programmers who doesn't) and use crappy arguments like "the code should comment itself" (for simple things :yes, for others: wrong!) or equally as bad "commit/change messages act as documentation" (wrong!). The idea behind the Wiki is that people can edit/improve things as they see fit, but I'd estimate 95% of the time, once people make pages in a Wiki + set things in motion, nobody ever goes back to organise or consolidate them.
I'll include this paragraph from my 2nd attempt:
An old boss of mine hated Wikis because, as he described them, they very quickly became "dumps" of old/dead/bloated information, and that housekeeping was rarely done on Wikis (and he's right). He argued that they act good for "presentation of reference data" but not good for training materials. And there is almost always a duplication of information in them given the presentation model and nature of what the Wiki is, in contrast to a single document (he would usually refer to PDFs in this case). As the years went on, I realised he was right.
P.S. -- The 2.00 release of nestech.txt was the final release by me
. I didn't do a good job of conveying this in the file at the time, but I did convey it on IRC and the nesdev mailing list: the document as of 2.00 was made public domain
. You do not need to ask for my permission to "edit it" or "improve it". People are encouraged to do whatever they want with it. If there's other "stuff" someone wrote "about" nestech.txt (incl. how it sucks), etc., they don't need my permission to do that. Everyone's entitled to do and say whatever they wish, in my eyes.