Suggestions to improve wiki's content

Discussion about the site's wiki, including bugs/issues encountered

Moderator: Moderators

Post Reply
darkhog
Posts: 192
Joined: Tue Jun 28, 2011 2:39 pm

Suggestions to improve wiki's content

Post by darkhog » Fri Oct 19, 2018 2:24 pm

1. When you need to put schematic of a board, put actual schematic of the board (as an image), instead of terrible ascii art as it is case with e.g. UNROM-512 schematic on the wiki.
2. When putting code samples, translate it to most used assemblers (in this moment AFAIK that would be ca65, NESASM and ASM6) as to not confuse new developers with assembler differences so they wouldn't have to translate it themselves and instead they could easily see it in a syntax they're most comfortable with (unless it's some exotic assembler in which case the dev probably knows what he's doing anyways).

I feel like if these two suggestions would be followed up on and put into practice across the wiki, it'd be much better source of information for developers new to NES.

lidnariq
Posts: 8792
Joined: Sun Apr 13, 2008 11:12 am
Location: Seattle

Re: Suggestions to improve wiki's content

Post by lidnariq » Fri Oct 19, 2018 2:37 pm

darkhog wrote:1. When you need to put schematic of a board, put actual schematic of the board (as an image), instead of terrible ascii art as it is case with e.g. UNROM-512 schematic on the wiki.
Please say more. I don't personally understand how the ASCII art schematic is obfuscatory, or how the same information would be clearer if drawn as a picture.

User avatar
rainwarrior
Posts: 7680
Joined: Sun Jan 22, 2012 12:03 pm
Location: Canada
Contact:

Re: Suggestions to improve wiki's content

Post by rainwarrior » Fri Oct 19, 2018 2:38 pm

1. I think there's an advantage of ascii diagrams in that they're much easier to edit, and less data to load. That said, I don't really care for one way or the other as long as the information is clearly organized, but all I'd say is that I doubt anyone will volunteer to change all the diagrams on the wiki to match your preference. The reason we have those diagrams at all is because someone was interested enough to make them in the first place.

2. I actually would not like to see the wiki cluttered with triplicates of every code sample. As long as it states which assembler to use, I think one version is fine. In most cases for small examples the syntax differences should be trivial/inconsequential to the example (sometimes none needs to be specified). Is there a specific code example that you thought was hard to understand in your not-favourite-assembler syntax?

darkhog
Posts: 192
Joined: Tue Jun 28, 2011 2:39 pm

Re: Suggestions to improve wiki's content

Post by darkhog » Sat Oct 20, 2018 4:36 am

Except these differences actually make some code non-trivial to translate, e.g. ca65 .bank syntax. Not to mention NESASM general weirdness.

Other code could be hidden in some openable box, like [spoiler] bbcode tag that is present on certain forums (not this one though).
lidnariq wrote:
darkhog wrote:1. When you need to put schematic of a board, put actual schematic of the board (as an image), instead of terrible ascii art as it is case with e.g. UNROM-512 schematic on the wiki.
Please say more. I don't personally understand how the ASCII art schematic is obfuscatory, or how the same information would be clearer if drawn as a picture.
I'm talking about actual board schematic, such as this one (random google search for PCB schematic):
Image

User avatar
rainwarrior
Posts: 7680
Joined: Sun Jan 22, 2012 12:03 pm
Location: Canada
Contact:

Re: Suggestions to improve wiki's content

Post by rainwarrior » Sat Oct 20, 2018 5:30 am

darkhog wrote:Except these differences actually make some code non-trivial to translate, e.g. ca65 .bank syntax. Not to mention NESASM general weirdness.
Could you point to a code example on the wiki that uses .bank, or otherwise a code example on the wiki that you think demonstrates one of these irreconcilable differences, or is otherwise confusing to you?

lidnariq
Posts: 8792
Joined: Sun Apr 13, 2008 11:12 am
Location: Seattle

Re: Suggestions to improve wiki's content

Post by lidnariq » Sat Oct 20, 2018 12:58 pm

darkhog wrote:I'm talking about actual board schematic, such as this one (random google search for PCB schematic):
I know what a schematic looks like. What I don't understand is how the same information drawn with lines or with ASCII art producing lines makes the information easier or harder to understand.

User avatar
dougeff
Posts: 2617
Joined: Fri May 08, 2015 7:17 pm
Location: DIGDUG
Contact:

Re: Suggestions to improve wiki's content

Post by dougeff » Sat Oct 20, 2018 1:44 pm

The wiki could use mapper specific example code* and/or templates.

*Like proper operation of MMC3 scanline counter.
nesdoug.com -- blog/tutorial on programming for the NES

User avatar
Banshaku
Posts: 2328
Joined: Tue Jun 24, 2008 8:38 pm
Location: Fukuoka, Japan
Contact:

Re: Suggestions to improve wiki's content

Post by Banshaku » Sat Oct 20, 2018 7:19 pm

The programmer's guide section was for that purpose when I created it but I was off the radar for a while so those examples never materialized ^^;;

But I agree, we need more programmer's example for basic usage so I wouldn't have had to create a lengthy thread about basic usage of mmc3 if there was already such sample, I guess.

I could try to make some of them but the main issue would be:

- do we stay assembler agnostic?
- does it has to be a complete compile-able sample or just a snippet?

Depending of the scope, it does make a difference on how long it takes to make.

User avatar
rainwarrior
Posts: 7680
Joined: Sun Jan 22, 2012 12:03 pm
Location: Canada
Contact:

Re: Suggestions to improve wiki's content

Post by rainwarrior » Sat Oct 20, 2018 7:34 pm

Banshaku wrote:- do we stay assembler agnostic?
I'd just suggest to use whichever assembler is most convenient, and maybe mention what it is. The bulk of any assembly code is mostly "agnostic" anyway, under normal circumstances, especially when we're talking about small didactic examples.
Banshaku wrote:- does it has to be a complete compile-able sample or just a snippet?
If you want to link a buildable project there's probably lots of other stuff you want to include. Attach it to a thread and link the thread from the wiki.

In my opinion, the primary point of a code example on the wiki should be to show how to do something. Making something you can copy-paste should be secondary to that. (Though, this is part of why I don't think it really matters which assembler is used. Reading and understanding code is hampered by these differences a lot less than copy-paste behaviour is.)

User avatar
tokumaru
Posts: 11469
Joined: Sat Feb 12, 2005 9:43 pm
Location: Rio de Janeiro - Brazil

Re: Suggestions to improve wiki's content

Post by tokumaru » Sat Oct 20, 2018 8:10 pm

As long as you avoid assembler-specific directives and special labels (local, anonymous, etc.), the code should be easy to follow by anyone. If you absolutely have to show more controversial tasks, such as defining variables, try to do it in a conventional way that's easy to understand (e.g. MyVar = $4F), even if it's not the way you'd do it in your own projects.

NESASM's discrepancies such as []s instead of ()s for indirection, HIGH() and LOW() instead of < and >, and so on, should be noted somewhere, but we can't forget that NESASM is the exception when it comes to 6502 syntax.

User avatar
Bregalad
Posts: 7768
Joined: Fri Nov 12, 2004 2:49 pm
Location: Chexbres, VD, Switzerland

Re: Suggestions to improve wiki's content

Post by Bregalad » Wed Oct 31, 2018 2:55 am

darkhog wrote:1. When you need to put schematic of a board, put actual schematic of the board (as an image), instead of terrible ascii art as it is case with e.g. UNROM-512 schematic on the wiki.
2. When putting code samples, translate it to most used assemblers (in this moment AFAIK that would be ca65, NESASM and ASM6) as to not confuse new developers with assembler differences so they wouldn't have to translate it themselves and instead they could easily see it in a syntax they're most comfortable with (unless it's some exotic assembler in which case the dev probably knows what he's doing anyways).

I feel like if these two suggestions would be followed up on and put into practice across the wiki, it'd be much better source of information for developers new to NES.
Sorry but your idea 2. is goddamn awful. We don't want every code sample to be there (and having to be maintained) thrice, nor do we want people to copy/paste code from the wiki into their code and ever expecting to work. This is just samples, they're supposed to show a general idea that can be reused in people's code, not to be copy/pasted into people's code.

As for idea 1, I agree actual schematic would look better than ASCII art, but how could we edit them ? Sure we could use SVG or something similar, but it'd be harder to integrate and edit.
I could try to make some of them but the main issue would be:

- do we stay assembler agnostic?
- does it has to be a complete compile-able sample or just a snippet?
My vote is for assembler agnostic and just a snippet.

Post Reply