It is currently Tue Oct 17, 2017 8:13 am

All times are UTC - 7 hours





Post new topic Reply to topic  [ 15 posts ] 
Author Message
PostPosted: Wed Apr 08, 2009 6:07 am 
Offline
User avatar

Joined: Mon Sep 27, 2004 8:33 am
Posts: 3715
Location: Central Texas, USA
MetalSlime wrote:
I think it would be useful to have 3 (or more) main sections:

1.For developers
2.For emulator writers
3.For hardware people
??4.For ROM-hackers??

Each section would have its own set of articles for the various topics (for example, there would be 3 articles about the PPU registers, one for each group). The articles in each section would be targetted at that specific group, and there would be links to the other sections' corresponding articles (if they exist) at the bottom for reference. Naturally there would be a lot of overlap, but I don't think that's a bad thing.

For a small example, the UxROM mapper page. Developers would probably want some basic information about how it works and some example code to get it running, but probably don't care about the information in "Solder Pad Config" or "Hardware" or "Variants". Hardware people probably want more detailed information about how it works and don't care about example code. So they'd each get their own UxROM page (with links to each other at the bottom)

For a bigger example, try imagining what would happen if we added code examples to the current NES_PPU page. That thing would be a monster (the bad kind).

The reason I am requesting this is because I often find (as a developer) that the current nesdevwiki articles are a little too technical. There have been many times where I wanted to edit them and add in more developer-friendly explanations with examples, but I didn't because there didn't seem to be a good place to stick them without overinflating the articles or messing up the flow.


Yes, we should identify distinct audiences and ensure that each can find the information it is interested in, and little more. How that is achieved is an open question; separate sections might not be the best way.

Everyone: overall structure of the NES and how everything fits together.
Developers: basic operation of a component, the normal way to use it, and techniques for getting the most out of it.
Emulator authors: more detailed operation, without programming techniques cluttering things.
Hardware developers: pinouts, timing, cartridge board layouts, etc.

ROM hackers as an audience is an interesting idea. It is a different perspective on things, influenced more by NES software than hardware.

The overview gives a framework for all the other descriptions, so they don't have to repeat how things fit together. And the developer documentation will likewise allow the emulator-oriented documentation to avoid having to mention how the registers generally work; it can get on with describing each register in full detail.

This division also modularizes decisions about how to present the information. Those working on developer documentation can focus on how to make it most useful to developers, without worrying about emulator authors or presenting every last detail.

In coming up with ideas, the PPU seems the best component to focus on, since it is so central to everything and has so many aspects. There are registers, like most other components, but then there's rendering behavior and timing and a ton of programming techniques.


Top
 Profile  
 
 Post subject:
PostPosted: Wed Apr 08, 2009 9:14 pm 
Offline
User avatar

Joined: Tue Jun 24, 2008 8:38 pm
Posts: 1517
Location: Fukuoka, Japan
The audience definition is the first goal and I think that we're already starting to agree on it since the same groups are always coming out (programmers, emu authors and hardware dev). This is important to know how to separate the information and find the people that can write the information since they know their own needs.

The main issue will always be how do we present it and I'm still scratching my head about that. Hmm.. There is good chance that we will have to make sections per audience but some content will be shared between them.

For example (maybe not a good one but that the first that came to my mind), as a programmer, I may want to know more about the 6502 instructions and most of the details about them can be used for me or an emu author but not a hardware developer. In that case, this information exist in the dev/emu section but not hardware one.

We need to define the needs of each groups since it will help us to map that information.

As a programmer, I will need to know about (sorry for the usage of the code tag for formatting):

Code:
- CPU
  + instruction set
- PPU
  + Init process
  + basic usage
  + any quirk to be careful about (ex: sprite 0 bug when value is $FF)
- Audio
  + how to use
  + Expansion audio, how to use
  + any quirk to be careful about
- Input
  + how to read peripheral
  + how to avoid glitch when using DMC
- Hardware
  + How to use mapper X
- Programming
  + Init process
  + reset, Irq, nmi, how to use
  + Sample for common pattern (music, graphic etc)
- Software
  + assembler
  + graphic/map editor
  + Music editor
  + Recommended emu list for development use


This could be a very simplified list of the needs of a programmer (all those section requires more sub section since they're too generic). Once we define each audience needs, we will need to focus on that and make sure that we provide only the information in a format that group understand well.


Top
 Profile  
 
 Post subject:
PostPosted: Wed Apr 08, 2009 11:12 pm 
Offline

Joined: Tue Mar 03, 2009 3:56 pm
Posts: 298
It would be cool if there were areas targeted at both new and experienced programmers. like tutorials for newbies and more raw data for experienced users


Top
 Profile  
 
 Post subject:
PostPosted: Thu Apr 09, 2009 12:23 am 
Offline
User avatar

Joined: Tue Jun 24, 2008 8:38 pm
Posts: 1517
Location: Fukuoka, Japan
frantik wrote:
It would be cool if there were areas targeted at both new and experienced programmers. like tutorials for newbies and more raw data for experienced users


I agree. The programmer's section will requires tutorial while the other ones (emulator author/hard dever) doesn't (I guess).

One thing that I don't know if it can be done for selecting content is something I saw on MSDN. You had a filter per "language" so you would only see the example based on your selected criterias in a page. For example, I could select in what page what I would like to see (emulator related, progarmmer only etc) and the filter would remove the extra section I don't need. Seems interesting but ... Maintenance will be hell without proper discipline. Maybe not a good idea..


Top
 Profile  
 
 Post subject:
PostPosted: Thu Apr 09, 2009 12:43 am 
Offline
User avatar

Joined: Tue Aug 19, 2008 11:01 pm
Posts: 186
Location: Japan
Could the different sections just be tabs off of the main page? ie a PPU_REGS page with 3+ tabs at the top, one for each audience?

_________________
MetalSlime runs away.


Top
 Profile  
 
 Post subject:
PostPosted: Thu Apr 09, 2009 4:58 am 
Offline
User avatar

Joined: Mon Sep 27, 2004 8:33 am
Posts: 3715
Location: Central Texas, USA
The site merely needs to satisfy each audience, not be literally divided into sections for each. A reader shouldn't have to categorize himself, and there shouldn't be ugly "This is for programmers, this is for emulator authors" everywhere. There might be an index of resources for those audiences, but the main organization wouldn't be explicitly along those lines.

The PPU might have a page that gives an overview of what it does, with a list of further content
Code:
Usage
    Initialization
    Pattern table
    Nametable
    Register usage
    Scrolling
    Split-screen
    ...
    More programming examples

Reference
    Warmup
    VBL
    Registers
    Rendering
    ...

Hardware
    Pinout
    Video signal
    ...

The programming examples would generally have more advanced techniques listed later. There would definitely be a page for new programmers, with links to basic tutorials and examples which wouldn't be shown on the PPU page.

Banshaku's list made it clear that it IS a good idea for us as designers of the site to categorize each page based on audience, since that has a big influence on the assumed knowledge and detail level.


Top
 Profile  
 
 Post subject:
PostPosted: Thu Apr 09, 2009 9:57 am 
Offline

Joined: Sun Sep 19, 2004 11:12 pm
Posts: 19086
Location: NE Indiana, USA (NTSC)
One of the complaints is that it might make the page "NES PPU" too long. In that case, the page was too long to begin with and should already have been split into pages like "NES PPU", "PPU Pattern Tables", "PPU Sprites", and "PPU Backgrounds".


Top
 Profile  
 
 Post subject:
PostPosted: Thu Apr 09, 2009 11:56 am 
Offline
User avatar

Joined: Mon Sep 27, 2004 8:33 am
Posts: 3715
Location: Central Texas, USA
The top-level PPU page would just have a two or three paragraph overview of what it does (renders graphics, has its own address/data bus, pattern table defines tile graphics, nametable background), then a list of links to the pages mentioned in my previous post. It would fit on most browser windows without scrolling.


Top
 Profile  
 
 Post subject:
PostPosted: Thu Apr 09, 2009 6:53 pm 
Offline
User avatar

Joined: Tue Jun 24, 2008 8:38 pm
Posts: 1517
Location: Fukuoka, Japan
blargg wrote:
The site merely needs to satisfy each audience, not be literally divided into sections for each.


You're right Blargg. I realized after that it didn't make much sense that way.

So we still need to try to find the needs of the emulator developers and hardware ones. I'm almost sure that they must be close in a way since those 2 audience wants to know the inner working of the hardware.

Once this list is done, this would help us to make the basic list of all required section that we can refine after with details for that specific audience.

What could be an example.. hmm..

Code:
- PPU
  (in no particular order since it's an example)
  + PPU Overview
  + Scroll register overview
     * Inner working (loopy)
     * Programming sample
  + Name table overview
     * Inner working
     * Programming sample
  + NTSC/PAl difference
     ! Known issues
  etc


Basically the PPU page of the original wiki can be segmented on each register/functionality with an overview, an hardware level explanation (when applicable, not always the case) and some dev example.

And we need to find the most generic topic (ex: CPU, PPU, Input device etc) to more specific (PPU/Scroll). In some case we can go deeper on a sub topic but we should avoid to go too deep when possible.

If we structure the wiki this way, we should be able to cover all aspect of the hardware very fast. But.. We still need some extra section. For example, I may have all the information in the world in front of me but it doesn't tell me how to get started using it. So we need a getting started section that could be specific to an audience (when applicable).

I will see if I can mock up a quick list of section/sub section soon.


Top
 Profile  
 
 Post subject:
PostPosted: Fri Apr 10, 2009 6:23 am 
Offline
User avatar

Joined: Mon Sep 27, 2004 8:33 am
Posts: 3715
Location: Central Texas, USA
Banshaku wrote:
So we still need to try to find the needs of the emulator developers and hardware ones. I'm almost sure that they must be close in a way since those 2 audience wants to know the inner working of the hardware.

I think the split is basically things the CPU can invoke/observe, and things that can only be observed with a meter or oscilloscope, or by looking at the circuit board. So descriptions of the software-visible effects of register accesses, open bus reads, cycle-accurate timing, quirks would satisfy emulator authors, and pinouts, nanosecond timing, voltages, circuit schematics, etc. would satisfy hardware developers.

The main four audiences (students, programmers, emulator authors, hardware developers) will be probably be roughly reflected in the organization, as evident in the PPU example.

Quote:
Code:
- PPU
  (in no particular order since it's an example)
  + PPU Overview
  + Scroll register overview
     * Inner working (loopy)
     * Programming sample
  + Name table overview
     * Inner working
     * Programming sample

Hmmm, I hadn't thought of mixing them together like that. I was thinking too inside the categories. This looks better, because then you can drill down for more detail. Hardware info will still be separate, and I think that's appropriate since most people are just dealing with NES software. Otherwise, the other three audiences will all eventually want the final details of something.

Quote:
If we structure the wiki this way, we should be able to cover all aspect of the hardware very fast. But.. We still need some extra section. For example, I may have all the information in the world in front of me but it doesn't tell me how to get started using it. So we need a getting started section that could be specific to an audience (when applicable).

Yes, definitely. The "main" organization would be around the NES architecture, but then there would be some pages collecting links to information related to a particular audience, and some material there that isn't even linked from the NES architecture. Things like 6502 programming introduction, test ROMs for emulators, NES code libraries, programming tools.


Top
 Profile  
 
 Post subject:
PostPosted: Fri Apr 10, 2009 6:31 pm 
Offline
User avatar

Joined: Tue Jun 24, 2008 8:38 pm
Posts: 1517
Location: Fukuoka, Japan
blargg wrote:
Hmmm, I hadn't thought of mixing them together like that. I was thinking too inside the categories. This looks better, because then you can drill down for more detail. Hardware info will still be separate, and I think that's appropriate since most people are just dealing with NES software. Otherwise, the other three audiences will all eventually want the final details of something.


Today I don't have much time to add to this conversion but one point that is important is that in the overview of a section (example scrolling overview), if a subsection is very specific to a group, we have to mention it. Example, if the loopy section has more understanding that is good for emulator author and not bring much to programmers, I won't really go inside that one as a programmer. May read it someday just for more understanding of the hardware. This way, I can focus on really what is important for me depending on my needs. When I read the current wiki, I'm not sure when it gets too technical if it can be useful for me or not (still from a programmer points of view).

edit 2:
removed comment since we posted at the same time and you may have missed it.


Last edited by Banshaku on Sat Apr 11, 2009 7:17 am, edited 1 time in total.

Top
 Profile  
 
 Post subject:
PostPosted: Sat Apr 11, 2009 7:13 am 
Offline
User avatar

Joined: Mon Sep 27, 2004 8:33 am
Posts: 3715
Location: Central Texas, USA
Excellent point, as there really is some information that is only of use to emulator authors, or programmers wanting to write obfuscated or highly intricate code. Heh, the current PPU page goes from normal usage to sprite evaluation and what cycles it reads bytes, and when it reads junk from OAM.


Top
 Profile  
 
 Post subject:
PostPosted: Sat Apr 11, 2009 7:18 am 
Offline
User avatar

Joined: Tue Jun 24, 2008 8:38 pm
Posts: 1517
Location: Fukuoka, Japan
After second thought, the comment in the overview section is maybe not the best thing to do. Maybe what would make more sense is some legend with icons. You put that icon beside a section when it's specific to a group. This reduce the amount of typing and it a more visual cue.

I will try to find something adequate. For now, the icon concept could be simple and easy to apply.


Top
 Profile  
 
 Post subject:
PostPosted: Sat Apr 11, 2009 2:21 pm 
Offline
User avatar

Joined: Mon Sep 27, 2004 8:33 am
Posts: 3715
Location: Central Texas, USA
I absolutely hate icons (in books, for example). They are distracting since they have their own channel which is usually empty, making the icon draw attention. I need to spend some time writing some example pages about the PPU so I can see how these ideas work in reality.


Top
 Profile  
 
 Post subject:
PostPosted: Sat Apr 11, 2009 6:29 pm 
Offline
User avatar

Joined: Tue Jun 24, 2008 8:38 pm
Posts: 1517
Location: Fukuoka, Japan
blargg wrote:
I absolutely hate icons (in books, for example). They are distracting since they have their own channel which is usually empty, making the icon draw attention. I need to spend some time writing some example pages about the PPU so I can see how these ideas work in reality.


I wrote the comment very fast without context so it may be harder to visualize. I don't want the icon to be in the content since you're right, it can be distracting. If it's that way, this mean the content what not separated in enough section.

What I had in mind is more to put icons beside the link in the overview. So if a specific section is for emu author only, an icon would be shown. If it's for everyone, we don't show anything. This way, instead of always filling the overview with "section X is more intended for emu authors", the icon beside the section name would be the cue.

ex:

Code:
- PPU
  (in no particular order since it's an example)
  + PPU Overview
  + Scroll register overview
     * Inner working (loopy) [E]
     * Programming sample  [P]
  + Name table overview
     * Inner working
     * Programming sample  [P]


In this quick example, the [E] icon means that we think this section would be more useful for emu author. The [P] was inserted beside all samples since we think mostly game programmer would find them useful.

I'm still not sure how to use them but I just want to try to find a way to quickly spot what is for who without too much writting since I know that many people will skip reading the overview details and just click on the following links. By placing a cue beside the link, that would help me to find what is useful for a specific group when it is intended for that group only.

Another idea I had is for the welcome page. First, you need to have a proper message that tells clearly what is the purpose of the site. Then I want to put two sections (or more if we find interesting one):

The first one would be the nes reference section. It contains all the information about the nes. The second one would be the getting started section that will guide you on how to start to program, tutorial that refers to section of the nes reference etc.

But like you mentioned, we should soon start to experiment on the test wiki. Just thinking all the time doesn't bring anything and since I'm visual, I will more see if it make sense once I try it. You can test anything you want since I intend to wipe it after we finalize the real one.


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 15 posts ] 

All times are UTC - 7 hours


Who is online

Users browsing this forum: Bing [Bot] and 2 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB® Forum Software © phpBB Group