Creating a decent manual
Moderator: Moderators
Creating a decent manual
I've been frustrated for awhile that many NES documents are difficult to read (or if it's me, I am not sure ). So I wondered if it would be possible to create a new document based on the old ones (but creating a more userfriendly layout instead of ASCII-drawings) and that would look more professional when printed.
Anyway I started experimenting. I've attached a very quick draft with some ideas. Assuming you're reading this and thinking this is a good idea, I'd love to get some constructive feedback and ideas.
Check out the very quick draftexample below:
http://dl.dropbox.com/u/2590713/Test.pdf
Anyway I started experimenting. I've attached a very quick draft with some ideas. Assuming you're reading this and thinking this is a good idea, I'd love to get some constructive feedback and ideas.
Check out the very quick draftexample below:
http://dl.dropbox.com/u/2590713/Test.pdf
- cpow
- NESICIDE developer
- Posts: 1097
- Joined: Mon Oct 13, 2008 7:55 pm
- Location: Minneapolis, MN
- Contact:
Re: Creating a decent manual
Comments:oRBIT2002 wrote:I've been frustrated for awhile that many NES documents are difficult to read (or if it's me, I am not sure ). So I wondered if it would be possible to create a new document based on the old ones (but creating a more userfriendly layout instead of ASCII-drawings) and that would look more professional when printed.
Anyway I started experimenting. I've attached a very quick draft with some ideas. Assuming you're reading this and thinking this is a good idea, I'd love to get some constructive feedback and ideas.
Check out the very quick draftexample below:
http://dl.dropbox.com/u/2590713/Test.pdf
Color is a bad idea...for the color blind audience.
Most of your readers read register tables from left-to-right so it's confusing to see the rightmost bitfield description first below the table. Suggest reversing the order of the bitfield descriptions under the table.
So much black space in the address cell is distracting. Consider moving the address above the table (outside it) and adding a name for the register. Then consider downplaying the black on the bit row.
Correction: Volume 0 = silent, 15 = max.
Nice job. I for one would love to see a comprehensive manual.
Re: Creating a decent manual
I share your frustration and am working on this exact project right now (in addition to writing an NES emulator). I want to make a document that looks as clean as Patrick Diskin's NESDoc.pdf but is at least as comprehensive as Martin Korth's everynes.txt. I'd really like to have everything in one document: descriptions of all the CPU instructions, every bit of every register, and every known mapper. Let me know if you would like to collaborate on this.oRBIT2002 wrote:I've been frustrated for awhile that many NES documents are difficult to read (or if it's me, I am not sure ). So I wondered if it would be possible to create a new document based on the old ones (but creating a more userfriendly layout instead of ASCII-drawings) and that would look more professional when printed.
I don't think this is a good format for the registers. As cpow pointed out, it's a bad idea to use color in the second row. However, the first row which is white text in a block box is good. As far as reading the registers starting from the left or right, I have reviewed some documents and it seems to be acceptable both ways. I actually prefer right to left. However, rather than just listing the bits in a table like you have done I find it more intuitive to make a line connecting the register to its description, as shown in the following example. Of course, this could also easily be set up as a table with empty cells (or maybe shaded cells) where the lines are.Anyway I started experimenting. I've attached a very quick draft with some ideas. Assuming you're reading this and thinking this is a good idea, I'd love to get some constructive feedback and ideas.
Check out the very quick draftexample below:
http://dl.dropbox.com/u/2590713/Test.pdf
Code: Select all
Mapper 7:
$8000-$FFFF: 76543210
|||||
|||||
|32K Swappable PRG ROM bank at $8000
|
Single Screen Mirroring Control
0 = Nametable at PPU $2000
1 = Nametable at PPU $2400
Might I advise everyone involved in this to take the time to review actual documentation from mainstream product vendors like Intel, Microchip Tech, Nuvoton (Winbond), T13 (for ATA specs), etc. to get an idea of how registers are displayed and individual bits or range of bits declared and described?
I can assure you (as someone who has written technical documentation and as someone who reads aforementioned specifications) that things like vertical lines aren't commonly used. All they end up doing is causing the reader to use his/her finger pressed against the monitor to try and map what line goes to what definition. In ASCII-based documents they end up wasting lots of vertical space (consider most people have monitors which in landscape mode, thus wider than they are tall).
I don't want this advice to dissuade you from your efforts or make you lose focus. I just want to point out that you should review existing documentation from well-established companies to get an idea of how to present the information. Try, for example, the Intel ICH9 Datasheet (look at item 14.1.3), the Winbond W83793G specification (look at item 8.4.2.2), the ATA8-ACS working draft specification (look at item 7.25.3 or 7.59.3), or the PIC24F Programmer's Reference Manual (look at register 2-1).
Hope this helps in some way.
I can assure you (as someone who has written technical documentation and as someone who reads aforementioned specifications) that things like vertical lines aren't commonly used. All they end up doing is causing the reader to use his/her finger pressed against the monitor to try and map what line goes to what definition. In ASCII-based documents they end up wasting lots of vertical space (consider most people have monitors which in landscape mode, thus wider than they are tall).
I don't want this advice to dissuade you from your efforts or make you lose focus. I just want to point out that you should review existing documentation from well-established companies to get an idea of how to present the information. Try, for example, the Intel ICH9 Datasheet (look at item 14.1.3), the Winbond W83793G specification (look at item 8.4.2.2), the ATA8-ACS working draft specification (look at item 7.25.3 or 7.59.3), or the PIC24F Programmer's Reference Manual (look at register 2-1).
Hope this helps in some way.
I've done a few updates to my draft, feel free to check it out:
http://dl.dropbox.com/u/2590713/NES/Ref2.pdf
http://dl.dropbox.com/u/2590713/NES/Ref2.pdf
I liked the older one better. Color helps separate things on an instantaneous, unconscious, and visceral level, so it's good to use for the people who aren't colorblind.
But I also like how the newer one displays bit numbers in the tables.
But I also like how the newer one displays bit numbers in the tables.
Here come the fortune cookies! Here come the fortune cookies! They're wearing paper hats!
I think the description values should be enumerated from largest to smallest to follow "left to right, top to bottom". I also like seeing the bits as in the first example. None of those registers have unimplemented bits, but when you get to registers that do it's helpful to see a grey block with lines through it; the current way could lead to some ambiguity without making a separate note.
- cpow
- NESICIDE developer
- Posts: 1097
- Joined: Mon Oct 13, 2008 7:55 pm
- Location: Minneapolis, MN
- Contact:
I am definitely a fan of the bitfield table, without it I agree the unimplemented bits disappear and potentially lead to confusion. It should not have disappeared in the second draft. Rather, a happy medium could be achieved. In most documents like this that I read the bitfield table is where bitfields (or singular bits) are introduced by *register-unique abbreviation* only. Then in the long-form table below the bitfield table both the bitfield and abbreviated name of the field are used to introduce the row, then a longer form name is given in the description, along with a table of bitfield values if they have un-obvious meanings such as the duty-cycle values.Dwedit wrote:I liked the older one better. Color helps separate things on an instantaneous, unconscious, and visceral level, so it's good to use for the people who aren't colorblind.
But I also like how the newer one displays bit numbers in the tables.
We had a thread (my response to blargg) where we went through a similar activity in the past but nothing ever came of it...perhaps this one can go further.
Thanks guys for the feedback!
I've created another draft where I've added the bitfield again (only bothered to update the first register at the moment..).
I am not sure how the bitfield definitions should be made (I use single letters at the moment). I think it's good that you can use both bitnumbers and letters for identification, but I am not sure how to implement the letters in the description-box without it starts to look messy.
Anyway check it out:
http://dl.dropbox.com/u/2590713/NES/Ref3.pdf
I've created another draft where I've added the bitfield again (only bothered to update the first register at the moment..).
I am not sure how the bitfield definitions should be made (I use single letters at the moment). I think it's good that you can use both bitnumbers and letters for identification, but I am not sure how to implement the letters in the description-box without it starts to look messy.
Anyway check it out:
http://dl.dropbox.com/u/2590713/NES/Ref3.pdf
Yes, it's important that we have a clean format that everyone can easily understand. However, it is more important that we have content. Shouldn't we focus on gathering and compiling correct information about the NES first and then worry about presentation style? My major problem with most existing documentation even more than the incompleteness and poor readability of some of it is that many documents are inconsistent with each other. For example: some claim that all of the bits of the registers of mappers 2 and 3 are used for bankswitching while others say only some bits are used. Also, I have yet to see a single document that fully explains the CPU, particularly the unofficial opcodes.... Are they the same as on a 6502? Do they differ between the NES and Famicom? Why do some emulators set certain bits the way they do (the ones not explained by existing documentation)? I think we need to find the answers to these questions before we can complete the kind comprehensive document about the NES we would all like.
Possibly because the mapper represented by the iNES mapper number has a superset of the hardware's functionality. The emulated mapper implements all bits while the actual hardware implements only some. In most of these cases, in the "variants" section on the wiki, I try to explain what would be required to implement in hardware the same extension that the iNES mapper implements.6T4 wrote:For example: some claim that all of the bits of the registers of mappers 2 and 3 are used for bankswitching while others say only some bits are used.
Have you checked 6502.org?Also, I have yet to see a single document that fully explains the CPU
Yes, with the possible exception of a couple unstable opcodes that produce analog-like behavior.particularly the unofficial opcodes.... Are they the same as on a 6502?
- cpow
- NESICIDE developer
- Posts: 1097
- Joined: Mon Oct 13, 2008 7:55 pm
- Location: Minneapolis, MN
- Contact:
Single-character bitfield names renders them pretty useless. My original point was that you could use something like "DUTY" independently in the rest of the documentation but if you shortened it to "D" you'd find yourself having to clarify it everywhere, *especially* since there's more than likely more than one field in one register that could be represented by "D" (there's a couple just in those four registers).oRBIT2002 wrote:Thanks guys for the feedback!
Also, you're still missing the link from the bitfield table to the long-form description. Something as simple as adding "D" underneath the 7:6 in the second part would be enough. Also, the column heading "Bit" should be "Field".
I agree with Tepples we need information, not just a format. However, as we're gathering information it'd be nice to have an agreed format. But then again, formats can be changed globally if necessary. Blah!