Skip to main content ↑ ↓
Topic: Improving the wiki (Read 158767 times) previous topic - next topic
0 Members and 2 Guests are viewing this topic.

Improving the wiki

Now that miniSphere has matured a fair bit, the wiki is kind of in a sorry state -- it still assumes that legacy Sphere is the only thing that exists. In other words, we're going to need new documentation.

I'd like to slowly start tackling this problem. Not just exposing the new API, but also having little tutorials in how to get started and use the tools that come with miniSphere, as I myself am kind of scratching my head on how to use them right now. Basically, it's not too easy to get started if you don't also have an editor available, even though Fat Cerberus has tried his best to document lots of things. I'm planning to document my findings as I try to build a miniSphere game from the ground up.

More importantly right now, we need to find a good way to distinguish legacy Sphere from miniSphere. Categorization is a given, of course, although I wonder if more shouldn't be done to really separate the two. After all, we have articles titled "API:Functions" that can get in the way here.

I also have to mention that the front page is locked from editing, so it's the articles themselves that will have to be changed.

My ideas:

  • Move all content from API:Functions into Legacy:API or perhaps Sphere1:API
  • Create a Sphere2:API article and "Sphere 2 API" category. Perhaps also categories for "Sphere 2 module" and "Sphere 2 script"?
  • Turn API:Functions into a simple disambiguation page that would link to Legacy:API and Sphere2:API.
  • Rewrite the Getting Started article for Sphere 2 (but preserve the current one on a Legacy: page)
  • Tutorial for writing a Cell script?
  • A tutorial that walks you through making a very basic game, and then extending it using several of the new APIs and modules
  • Copy Fat Cerberus' miniSphere docs into some articles and start writing articles based on all the functions and modules


Any thoughts/ideas/suggestions?

Re: Improving the wiki

Reply #1 –
Any thoughts specifically about moving all API: prepended articles with Legacy:? I think it makes a little more sense to make the difference extra clear. Could add a template that makes it clear that those are for old Sphere too.

Re: Improving the wiki

Reply #2 –
I'd agree with that change.  Should also add a note on the top of each Legacy: page that the Sphere v1 API is deprecated and new games should prefer Sphere v2 APIs (either core or miniRT, as appropriate) instead.

Re: Improving the wiki

Reply #3 –
That's pretty much what I meant with adding a little template, although I prefer stating you can really use either as long as you don't cross the streams (but Sphere 2 API is still recommend). The freedom of choice is a nice thing.

Re: Improving the wiki

Reply #4 –
Quote from: DaVince – on

That's pretty much what I meant with adding a little template, although I prefer stating you can really use either as long as you don't cross the streams (but Sphere 2 API is still recommend). The freedom of choice is a nice thing.


Hehe, "crossing the streams" is actually a really good metaphor.  The two APIs can coexist peacefully, even within the same game, as long as you don't try to pass objects from one version to a function expecting the other version.

Re: Improving the wiki

Reply #6 –
Quote from: Eggbert – on

While I usually tend to go with the Sphere 2 API, I've never really had any issues with mixing the two APIs.


Yep, that was the goal.  I watched past attempts at a Sphere successor and realized that Sphere v2 was never going to be successful unless developers were able to transition gradually.  An all-or-nothing upgrade was never going to be adopted, it had to be friendly to migration.  Avoiding conflicts between the two APIs was important.

The nice thing about this is that, because the lack of overlap is specifically enforced, Sphere v2 ends up being a complete clean break from Sphere v1, and can be made to be fully modern without being held back by legacy concerns.

Re: Improving the wiki (help wanted!)

Reply #7 –
Namespaces like API: seem to work weirdly in wiki software. Basically, with a single change in a PHP file, I just moved every single API: page to Legacy.

Now, all the references everywhere pointing to API: still need to be changed, but it's a start...

Edit: Help wanted!
The new API:Functions is now in place, but it's quite obvious that it needs a lot of work. Ultimately, I'd like this page to just explain some basic things and then display a list of all the functions, just like the Legacy functions page. Keeps it clean and clear.

So please, if anyone has some spare time, I'd like them to pick any function from the API reference and create a new article for it. For now, you can just copy whatever text is already there and add [[Category:Sphere 2 API]] at the end.
Here's an example.

I'm also thinking about having categories for each module that needs to be imported to be used. plus a "Native functions" category. Any thoughs on this?

Re: Improving the wiki

Reply #8 –
I rewrote Getting Started. It's still a work in progress, so feedback, additions and improvements are very welcome. (Just not too many additions; an introduction needs to stay brief and simple I think!)

Also, another help request: chase down any API: links and change them into Legacy: links. Except for the few new API: links that were made. :)

Re: Improving the wiki

Reply #9 –
I remember now why I ended up not contributing to the wiki: It's ridiculously slow.  It takes on average of 3-5 seconds to load each page, every time the page changes.  Even editing a single page is excruciating because I like to preview often.  I don't understand why it's so slow because the rest of the Spherical site, including the forums, is pretty snappy.

Re: Improving the wiki

Reply #10 –
I'm not really sure either. It might have something to do with the extensions; a bunch of them are loaded. Also, PHP 5 seems to be used.

I'd like to switch it to PHP 7 (it's quite literally twice as fast) and see what extensions can be dropped when I'm going to do the upgrade, but upgrading is a *huge hassle* so that won't be for a while.

The best thing to do right now is to edit the text in a text editor and submit it once you're entirely done with an article, I guess. I could also disable some less needed extensions for the time being.

Re: Improving the wiki

Reply #11 –
I don't think PHP 5 is the culprit for a 3 to 5 second slowdown. Even if PHP 7 was twice as fast, something else has to be responsible for even an extra second of wait time. I think it's one of the extensions, possibly one to do with spam control?
If you use code to help you code you can use less code to code. Also, I have approximate knowledge of many things.

Sphere-sfml here
Sphere Studio editor here

Re: Improving the wiki

Reply #12 –
Of course it's not the culprit , I just mean it would help performance regardless.

Anyway, will give it a look soon.

Re: Improving the wiki

Reply #13 –
I disabled a ton of extensions, including anti-spambot ones (since only members can edit articles and it's tightly controlled who's a member anyway). The page loading performance seems to be marginally better, so something else might be up, but at least it should help.
 

Re: Improving the wiki

Reply #14 –
Yeah, it at least seems tolerable now.  Time to get working on the Getting Started article!