User talk:Anaminus/API Documentation Changes
From Legacy Roblox Wiki
Jump to navigationJump to search
"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.
- 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)
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
- 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.
- 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.
- Actually, it's too simple. It needs more arguments on the properties to allow sensible autonomy.
- 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.
- 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)
- 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).
- 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"?
- 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)
- 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.
- 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.
- Templates were never meant to be a programming language, so I would still consider it a hack. I think it's only adding obscurity, which is what I really want to avoid. Anyone can copy and paste lines, but that doesn't make them magically know what it does. Not having a complete understanding leads to confusion which leads to bad edits. I can easily imagine a scenario where someone has to use trial and error to figure out whether they're using you're templates correctly. Personally, I want to be able to focus on properly documenting objects, without having to worry about how to get the page to conform to your system. --Anaminus 04:31, 8 May 2012 (EDT)
- It's a balance between having data accessible on other pages, and therefore consistency, over ease of writing the documentation more manually. Personally, I think that I went too far with the design existing system, which is too magic, and makes it difficult to find where to add new members to objects. However, I think having the ability to show the same data in different formats on other pages is worth the expense of the slightly more obtuse syntax. It's not ugly, it's just unusual. I realize that it's not just my opinion that counts here. Ultimately, it come down to what the other wiki users want.
- All it does is display the object's inherited members, and yet it demands that the entire source of a page be a certain way, and it requires that there be dozens of templates and transclusions. That isn't balanced at all. You think it's fine, but like you said, you don't write articles. An important factor in designing a system that others are going to be using, is that it's easy for them to understand and use. You're not paying enough attention to this.
- What I've found most is that users want a wiki that is helpful; one that actually does what it's supposed to do. How are writers supposed to fulfill this if the wiki is too difficult to edit? --Anaminus 16:54, 8 May 2012 (EDT)
- It's a balance between having data accessible on other pages, and therefore consistency, over ease of writing the documentation more manually. Personally, I think that I went too far with the design existing system, which is too magic, and makes it difficult to find where to add new members to objects. However, I think having the ability to show the same data in different formats on other pages is worth the expense of the slightly more obtuse syntax. It's not ugly, it's just unusual. I realize that it's not just my opinion that counts here. Ultimately, it come down to what the other wiki users want.
- Templates were never meant to be a programming language, so I would still consider it a hack. I think it's only adding obscurity, which is what I really want to avoid. Anyone can copy and paste lines, but that doesn't make them magically know what it does. Not having a complete understanding leads to confusion which leads to bad edits. I can easily imagine a scenario where someone has to use trial and error to figure out whether they're using you're templates correctly. Personally, I want to be able to focus on properly documenting objects, without having to worry about how to get the page to conform to your system. --Anaminus 04:31, 8 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.
- 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 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.
- 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.
- 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.
- I may now be moving too far towards complexity, but I have User:NXTBoy/Instance transcluding member descriptions from their respective pages - User:NXTBoy/Instance/Name and User:NXTBoy/Instance/Parent. This is the benefit of my metadata system - type once, transclude anywhere.
- I definitely don't like all those transclusions. That's another thing I'm trying to avoid. It's easy to transclude pages, and you should already know what happens when it gets out of control. What I really want is for the wiki to be less of a playground for making templates and more of what it's actually supposed to be. I want to keep the usage of templates to a minimum, because they cause everyone to lose focus on what they're supposed to be doing, which is documenting Roblox. --Anaminus 04:31, 8 May 2012 (EDT)
- Transclusions only go out of control in extreme cases. As for being a template playground ... Well, I became part of the wiki team solely due to my experience with templates. If you look over my contributions, a significant proportion is changes to templates. I don't see myself writing any articles any time soon.
- I definitely don't like all those transclusions. That's another thing I'm trying to avoid. It's easy to transclude pages, and you should already know what happens when it gets out of control. What I really want is for the wiki to be less of a playground for making templates and more of what it's actually supposed to be. I want to keep the usage of templates to a minimum, because they cause everyone to lose focus on what they're supposed to be doing, which is documenting Roblox. --Anaminus 04:31, 8 May 2012 (EDT)
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)
