Wikiwikiwikiwikiwiki

[pagefault]

How would people feel about converting the current documentation to a wiki. This would make updating and maintaing it a lot better.

[Jipcy]

From my knowledge of Wikis, they are web-based sites with different articles, with access-controlable editing abilities and stuff.

I can see that it might be easier for more people to contribute stuff. But how would we package these with the executable? Would there be any local version, or only web-based?

Also, there's the problem of reliability. ZSNES.com and SF.net are the only mostly reliable web servers that are associated with ZSNES.

What other specific benefits do you see from using a Wiki? I hope you've checked out the zsnes-docs CVS. It's certainly a LOT better than the 1.42 docs.

[adventure_of_link]

didn't we already have a docs wiki... ?

[Nach]

Also, there's the problem of reliability. ZSNES.com and SF.net are the only mostly reliable web servers that are associated with ZSNES.

Don't forget certain ZSNES devs also have access to pretty stable servers, such as edge.

[Jipcy]

such as edge.

I am unfamiliar with what this is. Explain?

Note: I'm a fairly long-winded guy, so I put my conclusion at the top here, with the rest of the stuff at the bottom. So that people are more likely to read the important stuff. (Look! I'm doing it again.)

Conclusion:
Anyway, I'm all for a Wiki becoming the official documentation, if it meets the following criteria:
1. Served on a highly reliable, secure server.
2. The new Wiki becomes the ONLY official documentation.
3. The location of the Wiki is shouted from the mountain-tops from all official sources of ZSNES, including in the ZSNES executable, in the WIPs, on the message board, etc etc etc.
4. There is at least cursory access-control on the Wiki to prevent malicious deletion.
5. The developers make an effort to maintain/update the parts of the documentation that would be difficult for non-developers to maintain (technical stuff about ZSNES).

Here's what I see for and against the current systems:

Documentation as they are:
pros:
- Already exist, don't have to change anything or work out a new system.
- Maintained on highly reliable servers, secure access to prevent malicious changes.
- Formatted in highly efficient XHTML.
cons:
- Limited access to some people that would otherwise want to contribute to the docs.
- Knowledge of XHTML is somewhat of a necessity.
- Few people are currently contributing to the docs.

A Wiki:
pros:
- Depending on how it's set up, anyone could contribute to it. Or, for example, anyone could contribute to the Wiki, and then designated "editors" would edit and approve the contributions, and then they show up on the main page.
- The developers could more easily access and maintain the highly technical information of which they are most knowledgeable, and that general users would have a hard time finding out.
cons:
- Possibly more difficult to package "local" copies of the documentation for distribution.
- Wikis may not output very lean/efficient HTML.
- The server needs to be very reliable, secure, and have a workable backup plan. SF already offers this. If the Wiki server is insecure, we run the risk of losing hard work and invaluable, possibly irreplaceable documentation.

[Nach]

such as edge.

I am unfamiliar with that this is. Explain?

Click the WWW icon at the end of this post.

5. The developers make an effort to maintain/update the parts of the documentation that would be difficult for non-developers to maintain (technical stuff about ZSNES).

Well...
I am on the doc team, and do contribute. Although in recent times my contributions to CVS have been infrequent, and most of my contributions lately are info in this forum here.

However before the next release, I plan on going over it for technical detail and correcting. One thing that comes to mind that the current what's new in CVS isn't accurate in several ways.

I prefer keeping what we have, since "it works". And I don't know how easy it is to package from a wiki... Perhaps have to wget -r it...
I am probably the one who will have to package it in the end.

But if we need the wiki, I can help arrange it.

[Jipcy]

Click the WWW icon at the end of this post.

Oh, that. Sorry.

5. The developers make an effort to maintain/update the parts of the documentation that would be difficult for non-developers to maintain (technical stuff about ZSNES).

Well...
I am on the doc team, and do contribute.

I didn't mean to minimize your contributions. I guess I was just expressing my frustration that it's very hard for me to find out some information about zsnes, because I'm not a developer and I'm not a programmer.

However before the next release, I plan on going over it for technical detail and correcting.

That is very encouraging news! Thank you!

One thing that comes to mind that the current what's new in CVS isn't accurate in several ways.

I'm aware of the problem. Xamenus has been creating the 1.43 changelog, I believe from the individual changelogs in the WIPs. Obviously, this changelog will need to be looked over very carefully before the next official release.

I prefer keeping what we have, since "it works".

I agree. I take a lot of pride in the HTML docs, and I hope to keep them as good, or better than they are.

I am probably the one who will have to package it in the end.

What do you mean by this?

[Nach]

However before the next release, I plan on going over it for technical detail and correcting.

That is very encouraging news! Thank you!

I wouldn't have it any other way.
I sure preassured RichardC about the docs, and making corrections to it back in the prior to 1.4 days.

I am probably the one who will have to package it in the end.

What do you mean by this?

I packaged the last 3 ZSNES releases, and I assume I will be packing the next several as well, so it's my task to get the docs from wherever and bundle them with the build.

[pagefault]

We need the documentation on a wiki.

[Deathlike2]

What's the link to the wiki? (if there is any set up)

There's a supposed wiki link in the "Annoucement" thread:
http://board.zsnes.com/phpBB2/viewtopic.php?t=3813

The link:
http://zsnes.game-host.org/wiki/

But eh.. there's a problem?

Edit:
I look at this thread:
http://board.zsnes.com/phpBB2/viewtopic.php?t=2806

There is mention of a Wiki.. but still no link though...

[xamenus]

I don't really see the point of having a wiki. If anything, it will probably just be a word for word copy of the html docs.

[Deathlike2]

I don't really see the point of having a wiki. If anything, it will probably just be a word for word copy of the html docs.

The major point of having a wiki is to be able to reference up to date information quickly. The docs are static files that normally don't change until an official update occurs (out of date information can be an annoyance -> more useless forum posts on the same topic).

When future WIPs are released, the Wiki can let you know what significant things have changed (well, that's what the changes.txt file does), and what games are affected (effectively a bug report list)... This is especially important when the current WIPs aren't bundled with the docs.

[Jipcy]

I've been thinking about the Wiki stuff. In my opinion, I think we should have a "ZSNES Knowledge Base" that would contain the information currently in the FAQ, as well the other parts of the official docs. The zsnes-docs project would still be necessary for producing the documentation included in official ZSNES releases.

The new ZSNES Knowledge Base would be the official online resource for all ZSNES related topics.

It would even be nice to have an SNES-wide knowledge base / wiki. In this way, we could provide high-quality information and documentation about all SNES emulators/emulation. Information for a single emulator would have higher value if it can be compared to similar documentation for another emulator.

Regardless of whether it's ZSNES-specific or SNES-wide, my greatest concern is about the longevity and stability of a project like this. I see no point in even starting something like this unless the hard work and man-hours put into this project would be fruitful.

I'm currently completely unfamiliar with the various Wiki software packages available. I have a slight concern against allowing anonymous edits. If possible, I would prefer a system where anyone could edit/submit changes for/create a page, but an "editor" or somebody would need to approve those changes before they are publicly visible.

Anyway, if we can find a stable server and create a backup plan, I am more than willing to help make a project like this a reality.

[pagefault]

I forgot to mention this earlier. The wiki is back online again.

http://zsnes.game-host.org/wiki/

Also I will be starting a log of xurrent and known issues on the main page which is still being made as you can http://zsnes.game-host.org see

[Jipcy]

Nice!

I was thinking that probably the best thing to do is to keep the official documentation, as it is now, for all pages but the FAQ. The FAQ information seems the type that would best fit in a Wiki. So, I'll see what I can do to work with this stuff sometime soon.

[kevman]

WTF is this shit?

Anyway, most of the stuff there will have to be discarded. Man, its HARD to believe its been a year since we built that....

[Jipcy]

Can someone give me elevated access to the Wiki so I can start working on updates? Username is Jipcy.

Also, who worked on the Spanish, French, and Portuguese translations?

[adventure_of_link]

iirc Mexandrew took care of the spanish.

[nemo]

How much demand is there for translated docs, and how much text is there in that? If the demand is high enough, I think I could put together a German doc. I don't think I have enough time for Japanese, as it would require a lot more work, and I don't know the technical vocabulary (Though most would be words borrowed basically with no modification from English, i.e. Emulator - > ??????)

Just a note, I'm only really asking the Devs and people who firsthand know of foreign users non-fluent in English this might help.

[pagefault]

I would like to set up a KB but I don't know how. Anyone have any experience?

[xamenus]

I just looked at the wiki. Turns out that it hasn't been updated in a long time. I'm just curious, but does anyone still find it useful/necessary?