Spherical forums

General Discussion => Site Comments => Topic started by: DaVince on June 11, 2017, 03:42:11 am

Title: Improving the wiki
Post by: DaVince on June 11, 2017, 03:42:11 am
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:


Any thoughts/ideas/suggestions?
Title: Re: Improving the wiki
Post by: DaVince on June 12, 2017, 01:57:17 am
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.
Title: Re: Improving the wiki
Post by: Fat Cerberus on June 12, 2017, 02:05:19 am
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.
Title: Re: Improving the wiki
Post by: DaVince on June 12, 2017, 02:08:56 am
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.
Title: Re: Improving the wiki
Post by: Fat Cerberus on June 12, 2017, 02:27:13 am

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.
Title: Re: Improving the wiki
Post by: Eggbertx on June 13, 2017, 10:07:41 am
While I usually tend to go with the Sphere 2 API, I've never really had any issues with mixing the two APIs.
Title: Re: Improving the wiki
Post by: Fat Cerberus on June 17, 2017, 11:11:47 am

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.
Title: Re: Improving the wiki (help wanted!)
Post by: DaVince on June 19, 2017, 05:02:06 am
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 (http://wiki.spheredev.org/API:Functions), 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. (http://wiki.spheredev.org/API:Require)

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?
Title: Re: Improving the wiki
Post by: DaVince on June 19, 2017, 09:09:25 am
I rewrote Getting Started (http://wiki.spheredev.org/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. :)
Title: Re: Improving the wiki
Post by: Fat Cerberus on June 21, 2017, 11:51:15 am
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.
Title: Re: Improving the wiki
Post by: DaVince on June 21, 2017, 02:06:35 pm
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.
Title: Re: Improving the wiki
Post by: Radnen on June 21, 2017, 10:42:47 pm
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?
Title: Re: Improving the wiki
Post by: DaVince on June 22, 2017, 11:35:44 am
Of course it's not the culprit , I just mean it would help performance regardless.

Anyway, will give it a look soon.
Title: Re: Improving the wiki
Post by: DaVince on June 22, 2017, 01:06:11 pm
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.
Title: Re: Improving the wiki
Post by: Fat Cerberus on June 22, 2017, 01:14:16 pm
Yeah, it at least seems tolerable now.  Time to get working on the Getting Started article!
Title: Re: Improving the wiki
Post by: DaVince on June 22, 2017, 01:16:10 pm
Oh, you might want to wait a little, or do some offline editing first. Casiotone is trying to work out why switching the server to PHP 7 breaks everything. (It also doesn't log any errors, so that's great too.)
Title: Re: Improving the wiki
Post by: Fat Cerberus on August 01, 2017, 12:20:19 pm
@DaVince: I noticed you added this template to the wiki today:
Quote
WARNING: This page has been written for the legacy Sphere 1.x API. While this API is supported in miniSphere, please do not mix API version 1 code with version 2 code as this will break things.

That isn't really true.  The APIs can be mixed freely, it's just that objects are not interchangeable (i.e. you can't say v2texture.blit() or Color.mix(v1color, v1color)).  That's built into the design, to make migration easier, and is something I've taken a lot of pains to ensure is possible.  If you have a lot of v1 code, this warning implies you need to go through your whole codebase and change them all to v2 at once, which is overkill.

I think a better warning might be to avoid using v1 APIs in all-new code; it's fine to mix them in a legacy context and incrementally introduce v2 stuff (my own Spectacles is like this in fact, as I've been too lazy to refactor it all :P).  I would change the template myself but I'm not sure what a good way to word that succinctly would be.
Title: Re: Improving the wiki
Post by: DaVince on August 01, 2017, 12:49:09 pm
Fair enough, I was having some trouble keeping it short and clear myself. I also meant to put it like what you said about the objects, but reading it again the current wording is indeed not clear enough.

Edit: changed the wording a little plus added a style to it. This should allow for a bit more text too.