User talk:Anaminus/API Documentation Changes

"API" Namespace

Does "API" make a good name? Does it describe the contents of the namespace? (a reference/documentation of Roblox classes) Alternatives might be "ClassRef", or "ObjectBrowser", I'm not really sure. Any suggestions? --Anaminus 01:41, 5 May 2012 (EDT)

I would be tempted to go for Object. API is a reasonable fit as well.

NXTBoy (talk • contribs)

08:26, 5 May 2012 (UTC)

I initially went against Object because member pages would be included under the namespace, but they're not "Objects". Thinking about it just now, since a member page would only be a subpage of an object page, Object may work after all. --Anaminus 04:37, 5 May 2012 (EDT)

I like API. Its nice and short, and make sense. - Quenty (talk • May 7)

Possible implementation, retaining autonomy

I've had a go at building a new template backend for a system like this. Unlike the old one, the data goes on the same page as the one presented to the user, and there are no auxiliary pages like /superclass and /properties. Have a look at them at User:NXTBoy/Instance, User:NXTBoy/BasePart, and User:NXTBoy/Part

NXTBoy (talk • contribs)

09:29, 5 May 2012 (UTC)

If unique and inherited members are going to be separated anyway, why not just completely remove inherited members and link to the superclass instead? --Anaminus 17:05, 6 May 2012 (EDT)

So that the viewer can instantly see which superclass they need to look at, rather than navigating further and further up the tree until they find the member they want.

NXTBoy (talk • contribs)

21:10, 6 May 2012 (UTC)

Great idea: get all of these done. Like you LocalSettings.php idea. --~ ⇒TomTomN00 @ 21:19, 6 May 2012 (UTC) 17:19, 6 May 2012 (EDT)

That makes sense. Though I dislike that the wikitext looks nothing like the page. I find it to be confusing and somewhat intimidating. --Anaminus 17:28, 6 May 2012 (EDT)

I don't think I can make it any simpler, short of perhaps replacing {{{1}}} and {{{2}}} with more descriptive names. I think it would be ok providing some HTML comments were put around it explaining what to do.

NXTBoy (talk • contribs)

21:42, 6 May 2012 (UTC)

Actually, it's too simple. It needs more arguments on the properties to allow sensible autonomy.

NXTBoy (talk • contribs)

21:57, 6 May 2012 (UTC)

Did an update. The old data structure didn't contain enough information to make the links or icons. Also, I've renamed the arguments to make it seem as non-magic as possible. Have another look at those pages (and their source).

NXTBoy (talk • contribs)

11:45, 7 May 2012 (UTC)

I can't really agree with it. It requires lots of hacks and dozens of templates, and while it is clever, it's not what I see as being simple. The goal of listing inherited members isn't worth this amount of complexity, especially when you could simply link to the superclass. --Anaminus 12:37, 7 May 2012 (EDT)

How are you defining complexity? The amount the user has to type to generate the pages? Or the amount of work the wiki does in the background? Both of these should be reduced considerably compared to the existing system. Which bits do you think are "hacks"?

NXTBoy (talk • contribs)

18:03, 7 May 2012 (UTC)

Another update done. Standardized template names, and added some explanation as to what each one does. See it here. I've realized that the member pages could also use a similar metadata concept. They could provide the brief description text for the object pages, instead of having the same sentence manually copied in both places. That would be incredibly trivial to implement, now that I'm thinking about this from a callback perspective.

NXTBoy (talk • contribs)

19:03, 7 May 2012 (UTC)

When I read the source, it should be apparent what each transclusion is, and I should be able to resolve them just by looking at them. Your implementation uses parameters to define which templates to use (definitely a hack, by the way), which makes it less apparent what is going on, and more difficult to read on the fly.
The average wiki writer (including myself) isn't going to be able to memorize how this works the first time around. Even if you've provided documentation, they're still going to have to reread it every time they want to edit a page. While it looks trivial to you (you are the one who made it), it's 'unintuitive to everyone else.

--Anaminus 20:04, 7 May 2012 (EDT)

I agree that my view of the complexity of the system will be biased. I'm not sure that templates-as-arguments are really a hack, no more than higher-order functions in lua. They solve the problem in a very concise way, with as few nested transclusions as possible. I disagree that the writer will need to read the documentation to edit page. The pattern of the metadata syntax is easy to see - I wouldn't expect anyone not to be able to add another member simply by copying and pasting another. As for adding new objects, the relative rarity with which that happens can justify having to read some documentation occasionally.

NXTBoy (talk • contribs)

07:01, 8 May 2012 (UTC)

The implementation I used to make that mockup uses what I might call "flat" transclusions, or transclusions that don't transclude anything else. What the template does is straight forward and apparent: display the provided data as a table. One can easily discern what it does when they read the source. There are no other templates required to get it to work properly.
You can see that example here.

Once again, if we're going to display inherited members and do other metadata-like things, we can't use templates, because they're not fit for the job. It is exactly why MediaWiki is adding Lua modules. If anything, we should invent a temporary system that would be simple to transfer over to Lua when it comes out.

--Anaminus 20:04, 7 May 2012 (EDT)

They may not be designed for the job, but they're certainly suitable for it. I think coming up with a temporary system is a mugs game. I reckon the Lua modules will be another year or two before they become part of mediawiki, and then the roblox wiki will likely stay stuck at 1.18 for a year or two after that. Heck, there's a chance that the Lua part of the upgrade won't be enabled when mediawiki finally were to get updated - after all, Mediawiki 1.18 comes with parserfunctions by default, yet we don't have them.

NXTBoy (talk • contribs)

07:01, 8 May 2012 (UTC)

Opinion

I agree with every single thing you've said on this page, except the following:

• I think the API namespace should instead be named the Documentation namespace.

Also, I have the following suggestions:

• Showing deprecation by putting a line through the object or member name, showing preliminary with italic text. These conventions are what the object browser uses, anyway.

And here are some remarks:

Making this system work might require complex template manipulation or might even be impossible to do automatically, but, really, your idea is so well-thought that it'd be worth it. Using namespaces and subpages gives us technical advantages provided by MediaWiki, such as being able to get the name of a member or object easily, or such as being able to list all the members specific to a class through the special pages.

Also, we really really really really need the ParserFunctions extension. We really need it. It would make templates easier to make, reduce the load time of these and give us more technical features that we didn't have before.

And here are some remarks concerning the disambiguation:

I think the disambiguation should be done with the templates I added on the wiki not long ago, which are identical to what Wikipedia uses. And I think we should choose the third option you mentioned, a mix of both redirecting and disambiguation pages. --JulienDethurens 14:01, 5 May 2012 (EDT)

"Documentation" seems a bit long for a namespace. It also doesn't really describe what it contains. Documentation of what? Anything? "Object" as a namespace makes more sense to me.
If you look at the mockup I provided, it takes preliminary and deprecated objects into account. Though that's more related to appearance anyway, so it doesn't need to be included in this outline.
If we were to wait out for the Lua extension to MediaWiki in place of using templates, it would provide cleaner, faster implementations. I'll experiment with it. --Anaminus 17:19, 6 May 2012 (EDT)

My Oppinion

I would support this happening, but it sometimes does take a while for them to update LocalSettings.php and add new extensions. --~ ⇒TomTomN00 @ 21:25, 5 May 2012 (UTC)