Creating a decent manual

Discuss emulation of the Nintendo Entertainment System and Famicom.

Moderator: Moderators

User avatar
oRBIT2002
Posts: 687
Joined: Sun Mar 19, 2006 3:06 am
Location: Gothenburg/Sweden

Creating a decent manual

Post by oRBIT2002 »

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
User avatar
cpow
NESICIDE developer
Posts: 1097
Joined: Mon Oct 13, 2008 7:55 pm
Location: Minneapolis, MN
Contact:

Re: Creating a decent manual

Post by cpow »

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
Comments:

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.
6T4
Posts: 48
Joined: Sat Feb 19, 2011 8:56 pm

Re: Creating a decent manual

Post by 6T4 »

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 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.
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
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.

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
User avatar
oRBIT2002
Posts: 687
Joined: Sun Mar 19, 2006 3:06 am
Location: Gothenburg/Sweden

Post by oRBIT2002 »

Thanks for the feedback. The lines connecting to the bits sounds like a good idea. Not sure how to do it in Microsoft Word but I'll investigate to see if it's possible with something similar.
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Post by koitsu »

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.
User avatar
oRBIT2002
Posts: 687
Joined: Sun Mar 19, 2006 3:06 am
Location: Gothenburg/Sweden

Post by oRBIT2002 »

I've done a few updates to my draft, feel free to check it out:
http://dl.dropbox.com/u/2590713/NES/Ref2.pdf
User avatar
Dwedit
Posts: 4924
Joined: Fri Nov 19, 2004 7:35 pm
Contact:

Post by Dwedit »

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.
Here come the fortune cookies! Here come the fortune cookies! They're wearing paper hats!
User avatar
kyuusaku
Posts: 1665
Joined: Mon Sep 27, 2004 2:13 pm

Post by kyuusaku »

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.
User avatar
cpow
NESICIDE developer
Posts: 1097
Joined: Mon Oct 13, 2008 7:55 pm
Location: Minneapolis, MN
Contact:

Post by cpow »

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.
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.

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.
lidnariq
Posts: 11432
Joined: Sun Apr 13, 2008 11:12 am

Post by lidnariq »

I actually really like both, other than the colorblindness issues. Just add the reference bitmask from the original draft to the description format of the revision and I'd be thrilled to keep a copy on my hdd.
3gengames
Formerly 65024U
Posts: 2284
Joined: Sat Mar 27, 2010 12:57 pm

Post by 3gengames »

Maybe take the colored one and just make it monochrome for the colorblind people? I love the 1st one. It makes it loads easier for me to understand the sound registers! Thanks!
User avatar
oRBIT2002
Posts: 687
Joined: Sun Mar 19, 2006 3:06 am
Location: Gothenburg/Sweden

Post by oRBIT2002 »

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
6T4
Posts: 48
Joined: Sat Feb 19, 2011 8:56 pm

Post by 6T4 »

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.
tepples
Posts: 22708
Joined: Sun Sep 19, 2004 11:12 pm
Location: NE Indiana, USA (NTSC)
Contact:

Post by tepples »

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.
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.
Also, I have yet to see a single document that fully explains the CPU
Have you checked 6502.org?
particularly the unofficial opcodes.... Are they the same as on a 6502?
Yes, with the possible exception of a couple unstable opcodes that produce analog-like behavior.
User avatar
cpow
NESICIDE developer
Posts: 1097
Joined: Mon Oct 13, 2008 7:55 pm
Location: Minneapolis, MN
Contact:

Post by cpow »

oRBIT2002 wrote:Thanks guys for the feedback!
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).

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!
Post Reply