News: 11 March 2016 - Forum Rules

Author Topic: Docs Improvement Project  (Read 4222 times)

zonk47

  • Sr. Member
  • ****
  • Posts: 343
    • View Profile
Docs Improvement Project
« on: February 27, 2016, 10:46:29 pm »
The purpose of this thread is to discuss approaches to improving the quality of technical documentation. At present information is spread all over the place and with a few exceptions (the Sega Master System for one, which is excellently documented at sms.org) it is an hours long process just to find the necessary documentation for learning. This is a serious deterrent to developing interest in hacking for all but the most determined. Time comes and goes and so do people and websites... a number of sites and resources which were relied on in the aughts no longer exist. Archive.org may or may not be reliable depending on a site's attitude towards robots, so we need to try to ensure that the information available isn't lost to circumstance. Many docs still rely on Zophar and who knows how long that site'll still be with us... it's changed hands many times over the years and gone in and out of dormancy, so it's hardly a reliable resource. Here at RHDN many docs are still stored as zip documents in ASCII format... this is hardly optimal in these times in which root access is increasingly hard to come by and always discouraged by OEMs and especially Microsoft. As the world moves towards the cloud, we also need to rely on the cloud to get information out there... wiki is the future and ASCII is the distant past.

We need to achieve the following:
- Consolidate resources and information in a single location that is reliable and mirrored.
- Organize the information in a manner that is not confusing
- Present it professionally
A good slave does not realize he is one; the best slave will not accept that he has become one.

Disch

  • Hero Member
  • *****
  • Posts: 2814
  • NES Junkie
    • View Profile
Re: Docs Improvement Project
« Reply #1 on: February 28, 2016, 01:35:14 am »
ASCII is forwards compatible with UTF-8 which is very much the present and the future.  Unless you're talking about Extended ASCII, which yes, was outdated 15 years ago (and frankly I wouldn't trust a doc that old anyway).

I completely agree with moving things to a wiki.  The nesdev scene has a wiki which attempts this... and does a reasonably good job of keeping the wiki updated with the latest discoveries and most up-to-date information, but is it organized and presented horribly and could really use a complete overhaul.  But getting the manpower to do that is difficult.  Though in a lot of ways, the nesdev wiki is a great example to learn from -- as you don't want to repeat its mistakes.


For this to be successful you need to plan out an organizational structure from the very beginning.  Nesdev's problem was they sort of slapped it all together as they went, so there's a lot of redundancy, and a lot of forked pages where some information on a topic is on one page, and other info you need on the same topic is on another, and the two are not easy to navigate.

I would say you should have separate pages for [at least] the following:

- High level concepts of how the system architecture functions (the concept of VBlank and rendering time, how BG layers are sorted, etc)
- A simplified explanation of how to make the system work (for intro homebrewers who just want to get started and don't want to have to get into gritty hypertechnical details)
- Summary pages of register descriptions (for at-a-glance references)
- Detailed pages of register descriptions
- Detailed pages of architecture procedures  (low level timing, what happens on each cycle, hardware quirks, etc)


Some duplicate info is unavoidable but it should be minimized as much as possible.

BlackDog61

  • Hero Member
  • *****
  • Posts: 784
    • View Profile
    • Super Robot Wars A Portable translation thread
Re: Docs Improvement Project
« Reply #2 on: February 28, 2016, 12:32:16 pm »
At some point reading the OP I thought this was going to be about what can be improved in the existing documentation on RHDN. But apparently that's not it.
So could we clarify what's being talked about here?
- Improving the contents of RHDN docs? (i.e. massive call for reviews?)
- Sorting info out in the existing RHDN docs &threads?
- Revamping existing RHDN info into another site? (Really?)
- Or all of the above adding info from the rest of the www? (which to me would sound like a dream in need of being turned into a step-by-step plan. 8))

I know we've been discussing how to raise awareness, and I personally take that as how to train newbies / how to wet the appetite of skilled people. The action plan can be different depending on that choice.

What will it be?

zonk47

  • Sr. Member
  • ****
  • Posts: 343
    • View Profile
Re: Docs Improvement Project
« Reply #3 on: February 28, 2016, 01:58:25 pm »
Disch, something like what was done at Wikibooks?

The way I see it, NesDev is dedicated exclusively to original NES development. NesDev users do not necessarily even approve of hacking. The same might be said for Wikipedia. After all, you don't see any black hat hacker wikibooks, do you? Probably the best approach would be to move the Wiki link at left to the Main column (to draw more attention and better convey that people might ought to click the Wiki in the first place), and reorganize the main DataCrystal page with a more instructional emphasis. We could improve the NES wikibook and make wikibooks for the other systems, and link directly to the docs.

The DataCrystal main page would look like this:
- [ link to rom hacking basics articles hosted on DataCrystal ]
- [ links to wikibooks ]

Blackdog, I don't think we need doc reviews. As far as documentation goes, we already have most or all of the information. Just need to make it so you don't have to open WinRAR to access it. And yeah, I agree that integrating information from forum posts is a priority.
« Last Edit: February 28, 2016, 05:13:27 pm by zonk47 »
A good slave does not realize he is one; the best slave will not accept that he has become one.

Disch

  • Hero Member
  • *****
  • Posts: 2814
  • NES Junkie
    • View Profile
Re: Docs Improvement Project
« Reply #4 on: February 28, 2016, 10:52:57 pm »
Disch, something like what was done at Wikibooks?

As far as NES system information goes, that page hardly even scratches the surface and is pretty useless in terms of content -- so it's hard to gauge whether or not it's a good organizational structure.  Having everything on one stub page certainly is not good, though.

Quote
The way I see it, NesDev is dedicated exclusively to original NES development. NesDev users do not necessarily even approve of hacking.

You said "technical information" so my mind immediately went to docs describing hardware behavior.  I didn't even consider that you were talking about things related to ROM hacking.

This kind of thing isn't necessarily shunned by the nesdev scene, it's just not the focus, nor does it have a place on the nesdev wiki.  If you're going to merge all of everything into one wiki I highly recommend keeping technical system information and ROM hacking specific stuff entirely separate, with the latter linking into the former when necessary.

Maybe I'm confused as to what the goal here is.  Are you trying to establish a new wiki?  Or are you trying to build on wikibooks?  Or are you trying to build on DataCrystal?  And what information are you trying to gather?



I agree that a wiki would negate the need for doc reviews as long as the wiki gets the maintenance it needs -- but that's really the hardest thing with wikis in general:  maintenance.

zonk47

  • Sr. Member
  • ****
  • Posts: 343
    • View Profile
Re: Docs Improvement Project
« Reply #5 on: February 29, 2016, 01:06:57 am »
I'm trying to decide. Making a new wiki seems pointless. There are no wikis/dedicated sites for most older consoles (in development terms at least), so that's an argument for scribing programming information for all the consoles to Data Crystal. Wikipedia people can be onerous fans of The Man and I really don't want to deal with them, so that's another +1 for Data Crystal.

Given the enthusiasm we've seen for the Translation Request List, I don't think maintenance is an issue here.

It seems like the thing to do, at the outset, would be to add a section for technical info to Data Crystal's navigation panel (the sidebar). Each system would necessarily have to have its own learners guide. Romhacking.net/start would also have a link from that panel, although I'm not sure what the point would be of keeping it when its info and structure could just be written to the wiki.

Here's what I propose for the new sidebar:

* Navigation
** mainpage|Data Crystal Main Page
** http://www.romhacking.net/|RHDN Home
** recentchanges-url|recentchanges
** helppage|help
* Hacking Basics|Hacking Basics
* Hacking
** 3DO|3DO
** Fujitsu FM |FM-7/Towns/Marty
** Gameboy|Gameboy/Color/Advance
** Gamecube|Gamecube
** GameGear|GameGear
** Genesis (Mega Drive)|Genesis/Mega Drive
** Lynx|Lynx
** MSX 1-2|MSX 1/2
** N64|N64
** Nintendo DS|Nintendo DS
** NES (Famicom)|NES/Famicom
** NEC PC|NEC PC-88/98
** Neo Geo|Neo Geo
** Neo Geo Pocket|Neo Geo Pocket/Color
** PC-FX|PC-FX
** Playstation|Playstation 1/2/3
** PSP|PSP
** Sega Master System|Sega Master System
** SNES (Super Famicom)|SNES/Super Famicom
** TurboGrafx-16 (PC Engine)|TurboGrafx-16/PC Engine
** Vita|Vita
** Wonderswan/Color|Wonderswan/Color
** X68000|X68000
* Game Specific
** http://www.romhacking.net/games/|RHDN Games List
** Category:3DO games|3DO
** Category:FM-7 games|FM-7
** Category:FM-Towns games|FM-Towns
** Category:FM-Towns Marty games|FM-Towns Marty
** Category:Nintendo Gamecube games|Gamecube
** Category:GB/C games|Gameboy/Color
** Category:GBA games|Gameboy Advance
** Category:Sega Genesis games|Genesis/Megadrive
** Category:Lynx Games|Lynx
** Category:MSX Games|MSX
** Category:MSX2 Games|MSX-2
** Category:Nintendo 64|N64
** Category:Nintendo DS|NDS
** Category:Neo Geo Pocket games|Neo Geo Pocket/Color
** Category:Neo Geo Pocket Color games|Neo Geo Pocket Color
** Category:NES games|NES/Famicom
** Category:NEC PC-88 games|PC-88
** Category:NEC PC-98 games|PC-98
** Category:PC-FX|PC-FX
** Category:Sony Playstation games|PS1
** Category:Sony Playstation 2 games|PS2
** Category:Sony Playstation 3 games|PS3
** Category:Sony PSP games|PSP
** Category:SNES games|SNES/Super Famicom
** Category:Sony PS Vita games|Vita
** Category:Wonderswan games|Wonderswan
** Category:Wonderswan Color games|Wonderswan Color
** Category:X68000 games|X68000
* Translations Request List|Translation Request List
* Community History
** Fan Translation Community History|Fan Translation Community History
« Last Edit: February 29, 2016, 09:52:24 am by zonk47 »
A good slave does not realize he is one; the best slave will not accept that he has become one.

Disch

  • Hero Member
  • *****
  • Posts: 2814
  • NES Junkie
    • View Profile
Re: Docs Improvement Project
« Reply #6 on: February 29, 2016, 09:34:09 am »
Well whatever your plan, the biggest problem you're going to have is recruiting people to build and maintain a wiki.  That the thing about a site like RHDN, is they can just accept submissions and throw stuff on a big pile with [relatively] low maintenance.  Wikis take constant attention, and new information can't be thrown on top of the pile, but rather has to be woven into it.


If I were to undertake this project, I would outline an organizational structure and create a few sample pages to flesh it out, get feedback on it and refine it... and once I have something that I feel is solid enough, start migrating a handful of docs over.  Then once you have some actual content to show off, then try to recruit people to contribute.

zonk47

  • Sr. Member
  • ****
  • Posts: 343
    • View Profile
Re: Docs Improvement Project
« Reply #7 on: February 29, 2016, 09:53:17 am »
Well whatever your plan, the biggest problem you're going to have is recruiting people to build and maintain a wiki.  That the thing about a site like RHDN, is they can just accept submissions and throw stuff on a big pile with [relatively] low maintenance.  Wikis take constant attention, and new information can't be thrown on top of the pile, but rather has to be woven into it.


If I were to undertake this project, I would outline an organizational structure and create a few sample pages to flesh it out, get feedback on it and refine it... and once I have something that I feel is solid enough, start migrating a handful of docs over.  Then once you have some actual content to show off, then try to recruit people to contribute.

I think there is a lot of drive and desire to push these improvements. I don't think participation will be a problem.

For the format, I think the game page template could be used: picture and basic stats floating at right, text at left. After that, a link to the Wikipedia page for that system, followed by links to articles concerning the following:

* cpu
* memory map
* memory/storage method and management ("mapping")
* video subsystem
* device i/o
* sound processing
* boot sequence (including sample programs)

Finally, a link to a dedicated site (having such things as pin-out information) at the bottom.

March 01, 2016, 11:32:23 am - (Auto Merged - Double Posts are not allowed before 7 days.)
No one's moving on this... well, so much for that idea!
« Last Edit: March 01, 2016, 11:32:23 am by zonk47 »
A good slave does not realize he is one; the best slave will not accept that he has become one.

Seihen

  • Sr. Member
  • ****
  • Posts: 402
    • View Profile
Re: Docs Improvement Project
« Reply #8 on: March 01, 2016, 06:37:56 pm »
... You could move on this idea? I mean, if you're passionate about it, why not make it happen? You yourself said that volunteers won't be a problem.

Disch

  • Hero Member
  • *****
  • Posts: 2814
  • NES Junkie
    • View Profile
Re: Docs Improvement Project
« Reply #9 on: March 01, 2016, 06:45:48 pm »
... Yeah.  It was your idea -- I expected that you were going to take point on it.

I gave feedback on what I thought you would need to do, and you basically said "yeah I can do all that" -- and then you didn't do any of it.  Did you just post something in hopes that someone else would do all the work?    :P

Do you even have a wiki set up?  You've been very vague on particulars.  Even if I wanted to help you with this I wouldn't know where you want me to start.

Like I said in my previous post:
1) Get a wiki set up
2) Put up some template pages to show how you want it organized
3) Put up a few pages of real content to show it in action
4) Get feedback
5) Adjust based on feedback
6) Repeat 4,5 until you feel comfortable you have a stable system
7) Recruit people to start supplying content en masse.


Those are steps you're going to have to do yourself if you want this to get done.  Nobody is just going to take the reigns on this for you.

zonk47

  • Sr. Member
  • ****
  • Posts: 343
    • View Profile
Re: Docs Improvement Project
« Reply #10 on: March 01, 2016, 09:39:57 pm »
No, see I meant to do it on DataCrystal. I start a wiki, there's no guarantee it will last. Last time I started a wiki, it got spammed to death. I could do it on DataCrystal, but the pages are protected. I need one of you to implement the revision to the side bar.
A good slave does not realize he is one; the best slave will not accept that he has become one.

Disch

  • Hero Member
  • *****
  • Posts: 2814
  • NES Junkie
    • View Profile
Re: Docs Improvement Project
« Reply #11 on: March 01, 2016, 09:46:16 pm »
Couldn't you get registered on Data Crystal to make the changes yourself?

Besides I wouldn't change the side-bar to link to your new section(s) until they are up and running.  I'd start by adding new pages and whatnot first -- then once it's there you can link to it from the main page.

zonk47

  • Sr. Member
  • ****
  • Posts: 343
    • View Profile
Re: Docs Improvement Project
« Reply #12 on: March 02, 2016, 01:31:02 am »
Couldn't you get registered on Data Crystal to make the changes yourself?

Besides I wouldn't change the side-bar to link to your new section(s) until they are up and running.  I'd start by adding new pages and whatnot first -- then once it's there you can link to it from the main page.

I'm registered but only admin can edit those pages.

Edit: I added a bunch of pages, including a page for the TG-16 and some reformatted articles  drawn from archaicpixels.com and an archive of text docs that I think only still exists on Internet Archive. Dealt with the video and the sound... controls next (not complicated)... but the Super CD is a completely different situation. These docs go into pretty much everything about it, with row after row of addresses and registers, but there is very little conceptual linkage, like you have to have first hand knowledge and experience with the internals of a CD-ROM drive to even know where to start. Which I think is the real problem standing in the way of hacking the system... it would be great if someone could explain which links to what, where, how, and why.

Also looking for PC-8801 info. I want to document it on DataCrystal, but I can't find any docs. Of course I could study an emulator -- and I probably will -- but I was hoping someone might know of some English language docs. I already have the memory map GIF on Wikipedia, so I don't need that. It only articulates the layout, however... what I need are hardware addresses and their functions.

Edit: there is no English PC-8801 info available (although if anyone wants to translate it all the necessary docs are on Internet Archive). The PC-9801 was released in the West as the "APC" minus the FM synth, so we're pretty good on that one.

March 05, 2016, 01:38:51 am - (Auto Merged - Double Posts are not allowed before 7 days.)
I found a source for the info I needed. Turns out the PC-8801 is an 8000 series machine. Wikipedia presented them as distinct architectures which lead me to think I needed manuals specific to the 8801. However I have located a Japanese fan site which explains the entire series... the 8801 is just a more flexible 8001.

I only found the fan site in question by doing a search for memory map diagrams images, and coming upon a diagram for the 8001 which resembled the m88 source code. I followed the site and discovered the page. Search engines are so less useful than they used to be... I wish I had an alternative.
« Last Edit: March 05, 2016, 01:38:51 am by zonk47 »
A good slave does not realize he is one; the best slave will not accept that he has become one.