- For main areas of discussion, make sure to use the 'add topic' button at the top.
Media Wiki Extensions
Plugin/Extensions we might want to use.
* Lua Syntax Highlighting: http://www.mediawiki.org/wiki/Extension:Scribunto -- While we may be interested in this for the capabilities it brings, Lua syntax highlighting is not one of them. -- SyntaxHighlight GeSHi Extension: http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi supports Lua highlighting and is included with MediaWiki 1.21 and higher so upgrading would add it.
* Category Tree extension: http://www.mediawiki.org/wiki/Extension:CategoryTree -- This could be used for example to show the CarbineNamespace category so people can drill down through each Package quickly
I'd love to see highlighting, but only if we can get the game API also to highlight.
Installed GeSHi and CategoryTree.
Thanks Pax. Can you do your magic to edit the styles for this to do the little box like the normal indented code setup does? I tested it out and it highlights just fine, but doesn't enclose the text in the box that helps it stand out.
I tried using CategoryTree CarbineNamespace however it appears to not be functioning properly. 1) it has +/- instead of arrows (This may be a setting) and 2) It doesn't list any of the items below the 1st category. The Mediawiki page had this to offer: Clicking the ► shows no sub-categories error Try to fix this by adding this code to LocalSettings.php: $wgCategoryTreeDefaultOptions['namespaces'] = array( 0, NS_CATEGORY, NS_FILE ); unsure if that will help or not though.
Organizing API Documentation
We definitely need a cleaner way of doing straight API documentation. A hundred sub categories on one page is too hard to navigate. Each API function should have its own page with syntax info (including arguments and returns), and example usage. Otherwise it's of no more use than the code hints in Houston.
I would rather see more task oriented stuff, such as what is up for ICComm and StoryPanel. These both document the code and show how it can be used. ICComm needs a more clear example still, as does StoryPanel, but they are more useful to non-professional coders to learn how to use the code in a useful way. -- Togglebutton
It looks like we're already working towards what you indicate in the first paragraph. But can you elaborate on the second paragraph? Only my second week working with the API and I'm not sure why you specifically call out ICCom and StoryPanel. -- jpeg
I wrote those two pieces to be more task focused. Specifically how to use them as a whole an not just raw API documentation. Supposedly we will be getting official API docs from CRB. No idea when. Documenting the entire API will be a long, tedious task. Producing wiki articles on how to use the API, and explaining them at the same time would be better use of time and of more use to people who haven't touched the game for addons before. Instead of writing a page for every function in the AbilityBook library, maybe do one page that describes working with it to solve a specific task. I haven't looked at that one myself, to give a concept there.
StoryPanel article is about using two functions of the MessageManager library, something that's useful but would be overlooked. I've had a few people ask about how to do Raid Warnings like in WoW. StoryPanel access is how you do that. We should hit the important parts of the API, to help people get tasks done, as opposed to just tossing something up that is already in Houston. --Togglebutton
Perhaps putting specific namespace overviews in the body of the Category page for that namespace? So for example the StoryPanel page would be the body of the Category:StoryPanel and the subcategories (Methods/variables) would be listed after all that. And I'm a bit confused on what you state in your first paragraph, the subcategories is because each of those has its own page like what you are asking.
They are listed as subcategories so they can be all grouped under the appropriate library/namespace. Or are you talking about the 1st pass at GameLib before categorization? --Sinaloit
I was trying to say that the first page of GameLib is terrible right now, with every function / method on one page. The first page should be just a list of the functions that links to the sub pages for each function. They've already started doing this for other libraries, we just need to make sure GameLib doesn't get missed. You can effectively ignore that part. Try to remember that I'm not a coder by trade, I'm in education, so I think about how to relay this information differently than someone who is purely a technical documentation focused individual. --Togglebutton
I added redirects to the main page for the library to reroute to the Category page instead. GameLib now routes to Category:GameLib unsure if this is the best route in the end but its a good intermediary step at least. Do you feel we should have the overview type information in its own page with a link to the methods/etc (The category) or should the overview type information be at the top of the category section? --Sinaloit
Nice job, Sinaloit. Could also just remove the GameLib page all together so that a search just turns up the Gamelib Category.
As for general descriptions on category pages, I agree. We need some sort of summary. Category:GameLib is an example where there is not a singular focus as to what it does and it would greatly help to explain what it does.
As for API Objects pages vs guides, I think we need both until CRB releases the official API docs. I don't think we need to be aggressive about getting every API object defined, but it'll definitely help the first time add on developer until the official docs are available.
Togglebutton, you want to write the first one to show as an example for the rest of us? -- jpeg
What I'm thinking is we have a short summary on the Category page, and then an Overview page for each section. The overview will go more in depth into some different things the library is regularly used for. For instance, the GameLib category page would have a paragraph or so about how it is used for interacting with the game data. The overview page would have this info, plus a few sample scripts, such as drawing a little popup window with a "character sheet" of basic character info using the functions in GameLib. Of course we can then link function calls to their wiki page for more info. I'll take care of this as soon as I can, I've got a couple papers to write by Tuesday.
That original GameLib page really no longer needs to exist. It was a page that I generated from code before going for categories instead. I think usage guides can be perfectly combined with the category pages, no? To take ToggleButton's Storypanel as an example: Why not simply add the relevant links on the category page, above the api listings? -- boe2
It would still be good to have a bit more description on the category pages themselves, in addition to usage guides. I'd like to see us focus more on usage articles, and as we do those, expand on the API documentation itself.
Removed content from GameLib page, now it is only a redirect. --Sinaloit
I'll just throw in my 2 cents here. I don't think we should be making a page for every method and trying to create a full-blown API reference. Carbine is doing that. Rather, perhaps the wiki can have pages for slightly higher-level concepts, such as the Apollo libraries (GameLib, XmlDoc, etc), key terms (Form, Event, etc), Carbine Addons, and systems (Packages, Sprites, etc).
To give a better idea, here is an example I would call "bad": http://www.wowwiki.com/World_of_Warcraft_API
And here is an example I would call "good," though I realize it's not a wiki: http://jsclass.jcoglan.com/enumerable.html
Here's another way to put it: Focus on the use cases of the API, not the API itself. So, for the GameLib page, we might have a "Units" section, which could describe GetPlayerUnit(), GetUnitById(), etc. Perhaps there would be another section called "World," which would describe GetWorldDifficulty(), GetWorldTimeOfDay(), etc.
I threw up an outline I made a long time ago, which wasn't originally meant for a wiki (and I'm still learning the syntax and tricks of the trade, so bear with me). I think a lot of those bullet points can be pages, and along the way we can define the important methods as they come up. I don't mind full API docs existing on this wiki, but something like that outline should come first IMO. People are screaming for tutorials, and I do believe a wiki can fill much of the "tutorial gap." But it won't if it's just a plain API reference (which Carbine has promised and Packet seems optimistic will be there at launch).
IF Carbine releases their own API documentation, I agree that the listing that I made so far is pointless. The thing is: the last time Bitwise mentioned this, he talked about lacking the manpower to do this and that must have been half a year ago. Personally, I don't see official CRB documentation happen any time soon. Where does Packetdancer's optimism come from? What does she know we don't?. This is knowledge that does affect the direction we should take with this wiki.
When I asked Packet about a week ago, she told me it is still Carbine's plan to have docs ready for release. She has also 'seen' actual documentation when she visited Carbine Studios, though that was some time ago.
Believe me, I'm skeptical too. We're trying to get confirmation from Bitwise, but people are busy yada yada. Right now I'm operating under the assumption that it exists, and it will be finished for release. I don't think that's unreasonable given that they've promised it on several occasions.
drafto, I think you're right about the outline. We need to get people aware of the basics since there is a huge need to replace what was lost in the forums wipe. I think it might be those of us active on the wiki right now to just grab a section or page and just start writing. We can then mark up the text like wikipedia does for things like clarification or other improvements.
With regards to the API docs, until the official docs come out we'll be the only real reference. I don't think we have to fill in the gaps of every single api object/function available. We just write or update pages of anything we're currently working with. No pressure to be completely documented.
The auto-generated pages also have a lot of errors. I just edited the RegisterAddon page, which had completely wrong arguments.
I definitely prefer drafto's suggestion of this http://jsclass.jcoglan.com/enumerable.html vs this http://www.wowwiki.com/World_of_Warcraft_API. I'm very new to lua, but having it presented the other way means I can learn instead of just copy/paste and brute force things in. I understand using methods and arguments, but sometimes I struggle with the translation from GAS and JS to lua. Having it organized like the jsclass page means that people can actually learn not just the how, but the why at the same time.
In the addon livestream it became clear that we shouldn't expect that official API reference in the near future. Bitwise referred on the stream to the NASA wiki (cool!) for API references, though mentioned it was very incomplete. That's why I just created stubs for all the remaining libs/funcions under Category:CarbineNamespace, using mediawiki's api. That way we at least have a API reference to refer aspiring devs to that is better organized than the XML documents in NASAdocs. I feel we also should get the events in there. If we ever do get an official reference guide, it's easy to automatically delete all the pages that fall under CarbineNamespace.
Github Project and Organiziation
So is anyone maintaining the Github project or organization? The one found here:
I posted an issue last week and haven't seen a reply on it or any other movement there. -- jpeg
I believe Draftomatic is the one who posted that --Sinaloit
Does anyone have contact info for Draftomatic? He made changes to the repo, but I don't think he understood what I was getting at. --jpeg
Lots of buzz going on in this wiki! I've been spinning in circles with exactly what to do with the git repo. I wanted an index page linking to all the projects, and a single repository with a README was a quick enough way to get that. I toyed with the idea of a Github Page (see http://dev.wildstarnasa.com), but I'm not sure there is enough content for that yet. I liked the idea as an alternative to making a new Page on the Wordpress site, because it would be editable by all. However, it's raw HTML/CSS, and being disconnected from Wordpress has a lot of consequences.
Anyway, I think I'll split it up into many repositories and see what that looks like. If it starts getting big, maybe we can continue with dev.wildstarnasa.com as a more attractive index/landing page.
Excellent news. Have you guys thought about moving the comment files into a separate NASA library? Then you can drop it into a repo and just add it to the top level projects as a submodule. Makes maintenance of common packages in the various projects easier.
And I still vote for managing it as a page on the wordpress site. Means control of the content stays with you core NASA folk.
That would mirror the old NASA repo pretty closely. I'll do it that way. -- drafto