Making PPU docs easier to understand (also nestech)

Discuss emulation of the Nintendo Entertainment System and Famicom.

Moderator: Moderators

tepples
Posts: 22708
Joined: Sun Sep 19, 2004 11:12 pm
Location: NE Indiana, USA (NTSC)
Contact:

Making PPU docs easier to understand (also nestech)

Post by tepples »

It has come to my attention that the PPU docs on the wiki aren't very well written.
In [url=https://forums.nesdev.com/viewtopic.php?p=224905#p224905]this post[/url], koitsu wrote:Strong matter of opinion, but I've maintained for a while that the Wiki does a *horrible, awful* job of teaching someone how NES graphics are "put together".
Trying to avoid a terrible, horrible, no good, very bad flashback...
koitsu wrote:I still maintain my nestech.txt document does a better job. I've said that for 20 years as someone who really didn't understand how the attribute table "fit in" to the whole scheme of things, until one day, my roommate explained it to me in such a way that something went off in my head and suddenly bam, it all made sense.
Would there be value in making a new revision of nestech.txt with the minimal changes to fix the known errata? Or other things that could be done to improve the wiki?
User avatar
dougeff
Posts: 3079
Joined: Fri May 08, 2015 7:17 pm

Re: Making PPU docs easier to understand (also nestech)

Post by dougeff »

After reading nestech.txt, I don't think it is much of an improvement on the wiki.

Perhaps a more visual approach would make it easier? Graphs / graphics rather than a wall of text.
nesdoug.com -- blog/tutorial on programming for the NES
User avatar
rainwarrior
Posts: 8732
Joined: Sun Jan 22, 2012 12:03 pm
Location: Canada
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by rainwarrior »

koitsu has nothing specific or actionable to say in that quote. So I don't think it's worth analyzing. All he's really saying is to read the document he wrote, which in itself is fine, I guess. I'm not going to go into opinions about whether it's better to read nestech.txt or the wiki (hey you can read both too, or neither), but I would at least guess that we might have improved the state of information at least a little in the 20 years that's passed since he wrote it. :P

Did koitsu have this problem understanding attributes today? 1 year ago? 5 years ago? 10 years ago? 20 years ago? The wiki has continually changed. Which version is bad? Is it better now? What's still bad? Answer those questions before you try to do something about it.

(...and yes there's a lot of stuff on the Wiki that could be improved-- there always is-- but as a general statement this is a useless thing to say.)

Also keep in mind that everyone learns differently. No one document is going to work well for everybody. In my opinion the Wiki is in general an excellent reference, though rewriting its articles instead as a teaching tutorial would be detrimental to its usefulness as reference. We could also have tutorial articles on the wiki, though (and there are a few, though), if someone capable wants to write some. Maybe koitsu would like to?
User avatar
rainwarrior
Posts: 8732
Joined: Sun Jan 22, 2012 12:03 pm
Location: Canada
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by rainwarrior »

Here's something I really don't understand:
https://wiki.nesdev.com/w/index.php/Nestech.txt

Why would someone want to read this? This is a set of proofreading notes of nestech.txt. What's the point? Do you really think someone is going to read nestech.txt and this wiki page side by side, read a wrong thing and then have it corrected immediately? If nestech.txt is for learning this is a terrible way to learn.

Would be much better to transfer the actual content of nestech.txt into this article (if koitsu wouldn't mind), and fix all those things that there are notes about instead. This whole article is just "list of tepples' complaints with nestech.txt" which I don't think is very helpful to anybody, really. If nestech.txt has tutorial/teaching value, make use of the content that has value.

We could have both the wiki's good and up to date reference, and teaching articles like nestech.txt side by side here, and maybe the one thing that we might glean from tepples' meta article about nestech.txt is that there's room for improvement in a 20 years old document. This isn't some either/or proposition, the whole point of the wiki is to collaborate and improve.


For example about 7 years ago loopy's "skinny" document was incorporated into the wiki, which a few years later was eventually transformed and merged into PPU scrolling, with a lot of good contributions along the way. I think is now in very good shape, better than either was before. We did this by collaborating, not by complaining that someone else's document is less accurate/good/readable/whatever than mine.
tepples
Posts: 22708
Joined: Sun Sep 19, 2004 11:12 pm
Location: NE Indiana, USA (NTSC)
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by tepples »

rainwarrior wrote:Why would someone want to read this? This is a set of proofreading notes of nestech.txt. What's the point? Do you really think someone is going to read nestech.txt and this wiki page side by side, read a wrong thing and then have it corrected immediately?
That was my thought sort of, to summarize what the community has learned since then. But you make a good point. I have moved that document to "Nestech.txt errata", with the intent of reserving "Nestech.txt" itself for what you go on to describe should koitsu allow it.
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Making PPU docs easier to understand (also nestech)

Post by koitsu »

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.
User avatar
Banshaku
Posts: 2417
Joined: Tue Jun 24, 2008 8:38 pm
Location: Japan
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by Banshaku »

Just want to chime in on the subject.

The wiki as a lot of information but expect you to know already about it. So when I went to the wiki to check how a mmc3 works to remember how to do banking, I stumbled on on many of the vocabulary and I had no idea what it was talking about until I tested some code myself. Once I understood how it work it did make sense but the way it was written was not useful for someone that doesn't know about the subject yet.

I do not remember what I got me confused in the first place since now I remembered how to use it but I will try to recheck and give some example so it may help write the documentation about it.

So it's not that the information is not good: there is a lot of factually right information compared to 20 years ago and it shows. The only problem is maybe the way it is explained is hard to get in but I'm not good at explaining thing clearly too so I wouldn't know how to improve it ^^;;
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Making PPU docs easier to understand (also nestech)

Post by koitsu »

^ This.

Conveying technical information clearly to readers is complex. If done right, it's actually possible to convey it to all types of people:

* Highly technical and familiar with the platform or info (e.g. a lot of people on nesdev)
* Highly technical + unfamiliar with the platform or info (e.g. some folks on nesdev -- I would put myself in this category WRT several subjects; Banshaku looking at MMC3 docs would be a good example)
* Semi-technical + unfamiliar (e.g. the common person wanting to do an emulator, or possibly homebrew) -- some hand-holding required but not excessive
* Not technical + unfamiliar (e.g. people completely unfamiliar with console development, 6502, etc.) -- usually require large amounts of hand-holding

It's something you get better at the more of it you do. I've always tended to write documentation intended for the "semi-technical + unfamiliar" crowd, because the highly technical crowds can still understand it.

I don't think "massively revamping" the Wiki would be the way to go, as it's not really feasible at this point. But doing some write-ups for people starting out would be better, on a per-subject basis; ex.:

* CPU (understanding 6502, along with aspects of the NES CPU that differ from other 6502-based systems (ex. no decimal mode)) -- Kasumi's recent helping of DocWaluigi is a great example (specifically for helping "not technical + unfamiliar" types)
* PPU (see above -- particularly really explaining pattern vs. name vs. attribute tables and the data formats)
* Mappers (stick with the mainstream ones; start with simple and work up to MMC3 -- no point in going past that, as by that point the user should understand the other existing docs)
* APU (this is one I myself would love to read, as I literally cannot get my brain around tons of audio aspects of the NES, no matter how hard I've tried for decades. Terminology plays a HUGE role here)

Language barrier will be a problem that cannot be immediately solved; easiest way to minimise that is to use "simpler" words, and/or provide multiple descriptions of a thing.
User avatar
Banshaku
Posts: 2417
Joined: Tue Jun 24, 2008 8:38 pm
Location: Japan
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by Banshaku »

I did use the MMC3 10 years ago when I started and I don't remember stumbling like that. Either my memory is playing tricks on me (back in the old days thing) and I think it was easier before or the vocabulary changed in the way that it now highly technical and less accessible. I think I still have a copy somewhere when I was managing the wiki so I will come back on it once I find the old files.

For the APU, I get confused easily because I do not know the tech speech. Maybe it's the language barrier since I'm not english native but for example, if you talk about the volume of a channel, even though not accurate, I will know right away that is is related on how loud this channel will be. Once you start talking about envelope, without explaining what it is, then my first image that come to my mind is writing a letter even though this seems to be the accurate word in that context (still, never used that except for nesdev). So it's not that the word is inaccurate, I'm guess it is the right one, but for someone that start on the subject, even though I'm highly technical on many thing, I do not know all of them and will get confused because of the vocabulary is foreign to me.
User avatar
rainwarrior
Posts: 8732
Joined: Sun Jan 22, 2012 12:03 pm
Location: Canada
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by rainwarrior »

We need reference material just as much as we need teaching material. They complement each other, and are not substitutes for each other. So, we can take a complaint like "the MMC3 page is hard to understand", but we always have to keep in mind who is this information for, why do they need it, what do they need it for. What do they already know?

Part of learning a technical topic like the NES is learning how to understand reference documents. The answer is not really to try to turn every reference document into a document for the layman. Conflating these two goals tends to make them bad at both simultaneously. Good reference needs to be fairly succint and clear, consistent and unambiguous. Good tutorials and teaching are often the opposite, and because everyone understands things differently, to really cover it you may need multiple perspectives, either in the same tutorial, or maybe just multiple tutorials.

Someone comes here, and asks a question. Often we point them at a reference document, and see if they understand. If they don't, they come back and ask another question hopefully. That's one way to teach, but sure it would be great if there was some better learning material to offer, especially good if it's actually integrated with the wiki.


nestech.txt is a good example. This could easily be a wiki article. It could be updated with the needed corrections, and it could be integrated with links to reference. It could also be organized with links and categorizations and landing pages that can guide users to it and other material that they need. nestech.txt is written for a certain kind of person, who needs an overview presented in this way. It won't ever be everyone's best tutorial, but it could work well for many.

So, tepples at some point was disappointed with nestech.txt's accumulated errors and instead of trying to update and repair the document, he wrote a bunch of notes on it and decided to keep it on the wiki. In my first paragraph here I mentioned that wiki articles should be written with the reader in mind. Who reads nestech.txt and why? If nestech.txt is a learning tool, do you actually expect an external list of errata to be understandable and useful to them or help them learn? I think any audience that would be able to find this article and understand it is already past the point of needing nestech.txt (or even wanting to know what's wrong with it).

On the other hand, it would have been a fine thing for tepples to put in his userspace pages on the wiki. Stuff like that can often be personally useful, especially if you want to do work to improve something like nestech.txt. As an article for general readers though? No. Not needed as reference. Not needed as tutorial. If there's a problem with nestech.txt fix the document. Don't clutter this space with both the document and this overlay on it. That just obfuscates everything. (It also seems to denigrate koitsu's work at the same time, which is also a problem. Drives people away from it who might actually find it useful.)


koitsu complains that a Wiki can never be good. Well, I respectfully disagree. We have a ton of good stuff on the wiki, and I've personally worked a lot to improve it in my time here, and watched others do so as well. I see people successfully learn from it every day. There's always, always room for improvement, and there's tons of stuff that I'd clean up if I had enough years (or if someone paid me) but as a volunteer effort I do what I can when I have the energy to commit to it, and I appreciate its existence every single day.

Yes, a single article written by a capable author, from one coherent viewpoint, is a good thing. Please write those. The wiki has space for those, or links to them.

Yes, wikis attract clutter. Point it out. Don't just tell us this obvious fact.


Fundamentally though, if you see something you don't like on the wiki. Point it out, or fix it. It can be better than it is, and it is better than it was, at least on longer time scales. There are regressions too, but we can and do fix those. It's very slow, and it's incremental, not a total revamp, but it's happening. Don't just complain that the wiki sucks, be specific about it, throw a note up on this board, maybe someone will have the time to make it a little better.

koitsu you can complain the wiki is a lost cause, I guess that's your opinion, but I very strongly disagree. You don't have to contribute to it, nobody does, but when you continually make unhelpful blanket statements to that effect, it's just a real drag. I think it hurts the overall scene because it seeds distrust in the very collaboration that has been slowly making progress here. If you wanna be critical in some specific way about any single part of the wiki, please do, but the way you're so generally dismissive of it I can't help but feel that you're really just trying to drive people away from it entirely, and I very much don't like this.


Tepples writing an article on what's wrong with nestech.txt hurts the utility of that document by poisoning the well for people that might actually have gotten something good from it. koitsu proclaiming the wiki to be trash forever does the same for the wiki. I think both would be better of if they were capable of leaning on each other rather than being posed in needless opposition.
User avatar
Kasumi
Posts: 1293
Joined: Wed Apr 02, 2008 2:09 pm

Re: Making PPU docs easier to understand (also nestech)

Post by Kasumi »

I do think a lot of NES related material is pretty dense. This doesn't apply to just the wiki, but on topic for the wiki I guess I have trouble "being bold" enough to edit it. I'd rather just write my own thing. And maybe that's true for a lot of other people. dougeff wrote his tutorials, shiru wrote his, etc.

I don't believe the wiki necessarily has to be the definitive source. And actually, I believe it's often more useful to have more resources than one "best" resource. To get my start, I downloaded most things on the NES front page. (Part of why is I didn't really have internet access at the time so I needed the most offline info I could get.) When I didn't understand a document, I switched to a different document. I can totally download the wiki, but in that situation had I not understood the wiki I'd just be... stuck. If NESTECH is better for some, and the wiki is better for some, I'd actually rather have both exist separately.

Maybe the way nerdy nights explains something doesn't click with me, but dougeff's explanation does. Given the wiki in any state of time, it's just one explanation.

I do have ideas about things I'd change about existing tutorials/the wiki, but similarly I'm not sure I'd contact the authors to change them because the change may hurt the material for just as many as it helps. Looping back to the start, that's why I have trouble justifying editing the wiki.

Here's a change I've always wished someone would make. I even left a comment about it on the talk page in... wow. 2011!

Code: Select all

value = (topleft << 0) | (topright << 2) | (bottomleft << 4) | (bottomright << 6)
It may be a little better to have this:

value = (topleft << 0) | (topright << 2) | (bottomleft << 4) | (bottomright << 6)

ordered like this:

value = (bottomright << 6) | (bottomleft << 4) | (topright << 2) | (topleft << 0)


Obviously the result is the same, but the second one keeps the order they'd be in the byte after the actual bit shifts. Bottomright would be in the far left of the byte, etc. It makes it easier to quickly glance and see the order. Just a thought, since I don't know if the current way is the standard way of representing bit shift equations or something. --Kasumi 02:24, 27 September 2011 (UTC)
I get bit by this pretty often when I do new things with attribute tables. But even then, I think, "It must be this way for a reason." Should I just make this change?

The only other thing I can specifically remember that is (to me) super overcomplicated is MMC3's CHR bank switching table. The and $FE stuff didn't make sense in my mind, so I just wrote test ROMs. I actually wrote a few huge posts on how to set up MMC3, but here was my explanation of the and $FE thing.
The way it describes CHR banks is pretty technical. But it's basically:
When writing a 1KB CHR bank (2, 3, 4, or 5 was last written to $8000), the value written to $8001 directly corresponds to 1KB in CHR. 0 is first 1KB of CHR, 1 is second 1KB of CHR, 2 is third KB of CHR etc.
When writing a 2KB CHR bank, (0 or 1 was last written to $8000) write the 1KB segment you want to start on. (But... one is subtracted from odd values. So you can only start at 0, 2, 4 etc.)
I think I can do a little better than the above, even. But it's a good start. Even if the wiki is only meant to be a reference rather than a tutorial, I think a clarification like that would help even people like me who are pretty good and who totally failed to understand what's there.

In general, though, I feel like the wiki is really, really awesome as reference! I wouldn't mind it having more "tutorialy" content, but I'd like it separate from the reference. I'm with rainwarrior's latest post that they complement each other.

Sort of like how there's the UNROM reference: https://wiki.nesdev.com/w/index.php/UxROM
And the UNROM "tutorial": https://wiki.nesdev.com/w/index.php/Programming_UNROM
The post I wrote the quote from is here: https://forums.nesdev.com/viewtopic.php ... c3#p209344
Which might make a good start for "Programming MMC3". But I'd definitely change explanations even in this, if it wasn't targeted to that specific person.

I actually deeply enjoy writing this kind of material and trying to make things as clear and simple as possible, but it's also time consuming and hard to justify the time for. But obviously everyone has that same problem, so here we are. :lol: I really, really, really want to write NES tutorial content, but it always loses to other things I should be doing. It's hard to do it without immediate need. That's why I like the topic I'm posting in recently. It gives me a reason to write the content, as well as immediate feedback on what's not clear.

I guess the short version of my post: I agree a lot with rainwarrior, but am personally scared to make changes. Check out the two above, though. Any reason not to make those changes? Then I'll finally do it. (I realize one is slightly off topic since it's not PPU related.)
User avatar
Banshaku
Posts: 2417
Joined: Tue Jun 24, 2008 8:38 pm
Location: Japan
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by Banshaku »

The wiki suck :lol:

Jest aside, I do not think that Koitsu is against the wiki but just mean that we need a way to explain nes things better. If he was such against it, he would not have gladly gave space for it when I requested it from him in 2009, when the previous hosting was unfortunately unstable and was hard to reach. It was alreardy a good source of aggregated information (for the time) and people really wanted to access it. So I decided to do something about and remember passing 1 weekend copying article one by one on the new server (I didn't know about wikimedia at all and wanted to extract the content as fast as possible) and he gladly helped support the update of the software, the offline export (we had that before).

When I moved it, my goal was to make it easier. I started by creating those ugly blue box thing in the hope to start to segregate the data in technical and reference but now in hindsight, since I was a nes beginner anyway, I think that I would have not done a good job either way. I really believed in the wiki and wanted to make it better but I just dropped out of the face of nesdev.

Kasumi comment about the chr thing is one example. I still read it today it may have meaning in some context (I do not know which one, for emulator author?) but for developer, I had no idea what it meant. Now I'm checking if I can do something with the scanline counter that I didn't use for a long time but I didn't find my answer yet (I will post a thread later).

So the wiki is fine but some place are ambiguous but I do not know how to update them. We need more article in the programming guide section that explain concept without the inner working. I guess that would count in the tutorial thing.
User avatar
rainwarrior
Posts: 8732
Joined: Sun Jan 22, 2012 12:03 pm
Location: Canada
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by rainwarrior »

Kasumi wrote:(2 specific suggestions for the Wiki)
You have a wiki account, right? I'd say go ahead and make both those changes.

Would agree on the first one that the more big-endian oriented version you propose is better.

I'd agree on the MMC3 thing being a little obtuse. Maybe I'd suggest turning the "AND $FE" / "OR 1" thing into a two-row cell that just says R0 or R1, then a statement that "A 2k CHR bank is only capable of selecting an even numbered bank. The lowest bit of the register is ignored.") Somemthing along the lines of that or what you wrote would be an improvement, I think.
User avatar
Banshaku
Posts: 2417
Joined: Tue Jun 24, 2008 8:38 pm
Location: Japan
Contact:

Re: Making PPU docs easier to understand (also nestech)

Post by Banshaku »

rainwarrior wrote:
Kasumi wrote:(2 specific suggestions for the Wiki)
I'd agree on the MMC3 thing being a little obtuse. Maybe I'd suggest turning the "AND $FE" / "OR 1" thing into a two-row cell that just says R0 or R1, then a statement that "A 2k CHR bank is only capable of selecting an even numbered bank. The lowest bit of the register is ignored.") Somemthing along the lines of that or what you wrote would be an improvement, I think.
I didn't know about the 2k is only capable of selecting even banks, didn't even realize from the text. Maybe that why I had weird bank issue recently and need to recheck my constants :lol:

As for R0, R1 etc, what does that means? I have no idea.
lidnariq
Posts: 11432
Joined: Sun Apr 13, 2008 11:12 am

Re: Making PPU docs easier to understand (also nestech)

Post by lidnariq »

rainwarrior wrote:a two-row cell that just says R0 or R1, then a statement that "A 2k CHR bank is only capable of selecting an even numbered bank. The lowest bit of the register is ignored.")
That is basically how we presented the VRC6. And it's approximately how Disch's docs also worked, although his bitshift notation felt obtuse to me.
Post Reply