Skip to main content

News

Topic: Improving the wiki (Read 7508 times) previous topic - next topic

0 Members and 1 Guest are viewing this topic.
  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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?
  • Last Edit: June 11, 2017, 09:21:26 am by DaVince

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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.

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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.

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
Re: Improving the wiki
Reply #4

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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

Re: Improving the wiki
Reply #5
While I usually tend to go with the Sphere 2 API, I've never really had any issues with mixing the two APIs.

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
Re: Improving the wiki
Reply #6

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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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?
  • Last Edit: June 19, 2017, 06:29:44 am by DaVince

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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. :)

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
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.
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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.

  • Radnen
  • [*][*][*][*][*]
  • Senior Staff
  • Wise Warrior
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

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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.

  • DaVince
  • [*][*][*][*][*]
  • Administrator
  • Used Sphere for, like, half my life
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.
  • Last Edit: June 22, 2017, 01:14:13 pm by DaVince

  • Fat Cerberus
  • [*][*][*][*][*]
  • Global Moderator
  • Sphere Developer
Re: Improving the wiki
Reply #14
Yeah, it at least seems tolerable now.  Time to get working on the Getting Started article!
neoSphere 5.9.2 - neoSphere engine - Cell compiler - SSj debugger
forum thread | on GitHub