[Poll] Which style for the LUA reference on the wiki?

EDIT: For a preview of what the private beta looks like, see this post.

Hello. The official wiki has not been updated after G&K and it is not possible to edit it for us. As a result there is currently no good documentation source for modders. I intend to fix by updating the CivFanatics wiki. I already have a nice piece of code that mixes data from multiples sources (official wiki, LUA dumps, etc) in order to produce a formatted output and upload it to the CF wiki.

But I need to know which style you prefer. Currently three styles are present on the wiki, despite a few number of pages. Here are the competitors:

2k style
Pros: it's simple but robust. The summary displays a quick listing while the page itself is a detailed listing. Functions' details are immediately available by clicking a link on the summary, without any page loading.
Cons: it's long (but it could be made shorter) and painful to browse, and we cannot display too much information per function (no long examples). It could be made better with the table of contents on the right.

Categorized listing
Pros: it's elegant and short, and the categorization can be helpful.
Cons: the categorization actually does not really work that well (maybe there should be fewer categories), and you always need to open a new page in order to see the details of a function. Should we try to provide more informations, the result would be quickly disturbing.

Array
Pros: most of the information is here and it's still very compact.
Cons: it's a giant ugly array. While the provided civ4 example has a reasonable length, civ5 objects are monsters with many many functions.

Which do you prefer?

Finally, other suggestions are welcome but please note this is only a wiki. So forget sophisticated formatting and javascript, most of those would not work. We need to stick to the wiki formatting for the most part.

PS: No, no actual poll. I am more interested in your comments than in numbers.
PPS: All links would be blue (red is only for missing links).

From the perspective of someone not knowing but wanting to get into LUA, I like the 2K style, simply because it gives examples of the format (If the examples are actually existing)

Glad to learn you're jumping on the LUA wagon, Pouakai.

Now the full content would be available in every format, it's just that in the second and third ones you would have to click a link and open a new page to learn more. Does it affect your preference?
EDIT: However most of the time you would click only to discover there is NO available example, this would be quite frustrating.

Some tests later.

Once the 2k style is purged of all blanks, it is easy to realize there is about no example and parameters' description: Test2
The result is clearly not there is almost no benefit while the useless space consumption is obvious.

So I made another try with a table, I like the result, most of the informations are readily available: Test3. It could be combined with few categories maybe, and the summary could be included in a row below the function but there is rarely a summary available. The example and parameters documentation would only be displayed on the function's page but since they are rarely available anyway...

EDIT: And here is a variant: Test4

So long as there are examples at the end... That is the most frustrating thing with current wikis.

Craig_Sutter said:

So long as there are examples at the end... That is the most frustrating thing with current wikis.

Click to expand...

I think there is a misunderstanding here. I intend to organize the wiki, ensure the content is there and properly formatted, with explanations regarding data types and other core elements.

But I am certainly not going to write thousand examples. I am not even sure I will write a single one.
The content will be mostly the one you will find on the vanilla wiki. But up-to-date, conveniently formatted, with consistent data types and full of automatically gathered informations.
Now maybe I will try to extract single-line examples from the LUA game files but the result would probably be useless.

Is it possible to make a combo out of categorized listing and the array setup?
So that you do not get a single page per function, but an array per category?

Because sometimes you don't know exactly for what you are searching, or in which class it is available, so you need all the functions to search in them.
But then again sometimes you deal only with 1 class, and want only to have the functions in this class, and not all the functions.

For the Civ4 Python, there are 2 APIs available, one listing, and an array per category. I tend to use both, due to the different needs.

DonQuiche said:

PS: No, no actual poll. I am more interested in your comments than in numbers.

Click to expand...

Oh, I can add one later.
That's IMHO even preferable. You can first discuss the pros and cons without voting, and if you have narrowed the exact options down to something more specific, then you can poll it out.
If you don't poll it, the discussion tends to go to a consensus decision, which can need too long and active participators might drop out, because it's too tiring.

The_J said:

Is it possible to make a combo out of categorized listing and the array setup? So that you do not get a single page per function, but an array per category?

Click to expand...

Sure, this is actually something I wanted to try with test3.

For the Civ4 Python, there are 2 APIs available, one listing, and an array per category. I tend to use both, due to the different needs.

Click to expand...

Interesting, I didn't see such an example. Could you show me one please?
Now this is also something I thought about but I wasn't sure about it, hence why I would like to see an example.

Other things I imagined are:
* Cross-pages categories, so that you could quickly see all resources-related functions, whether they are in City or in Plot
* One global index: sometimes it's useful.

But obviously those two features would require to have one page per function. While I can easily have them automatically generated, it bothers me to have tons of nearly empty pages, and that all links will be blue in the types' pages. I would then need another way to quickly emphasize which links do contain examples or parameters descriptions. Also, categories is the only way to have a wiki that is easy to edit: while my pages generator doesn't need them, humans will because they won't edit five pages in a row just to correct one mistake in a function signature. They should fix one, or atmost two, pages (the function page and the type page).

Oh, I can add one later.
That's IMHO even preferable. You can first discuss the pros and cons without voting, and if you have narrowed the exact options down to something more specific, then you can poll it out.
If you don't poll it, the discussion tends to go to a consensus decision, which can need too long and active participators might drop out, because it's too tiring.

Click to expand...

This is something I will think about. When I started I wasn't too sure about how much content was available, what people need, love or hate, which constrains I would face (the thing about generating pages for all functions or not for example), etc. Hence why I was more interested in a discussion while I ran experiments. A poll would have been quite irrelevant at that stage.
But if I can, in the end, link three models and ask people which one they like best, why not? I think I will start a new thread then.


PS: Is there a way to flag a page for auto-deletion? Or should I add those to a dedicated category? Do you have some way to quickly delete 1k pages for example (I won't generate them if you cannot delete them in a batch)?

First of all, thanks so much for taking on this effort! Very much appreciated.

The methods need to be in a single page (for each object type) with their args and return values. I use the wiki in two ways:

1. To try to guess what a method does. The first clue is always the list of args and return value.
2. To remind myself how to use a method (even if I've used it 100 times).

Having to go to a separate page to do this just slows the process. For #2 specifically, I would get very annoyed if I had to guess the category (or use cntl-f) to find something rather than a simple alphabetical lookup.

If someone wants to categorize or build tables, that's fine. It can be done later and separately, with links that take you right to the specific method. There is no reason for this kind of organization to take away from functionality.

@Pzyryk
I do agree with you on the fact that we need a page per type where functions are listed with their signatures (args and returned values) because this information is so important.

While I proposed alternative choices that do not expose signatures, I do not expect them to get many support but I want to be sure.

Regarding categories, global index, etc, they would not replace the page we talked about. They would be an additional way to browse the functions and not the default one. And it does not remove functionality: unless we opt for the 2k style where everything is presented on a single page, a mere signatures listing like test3 does not expose parameters description or examples, so we would need one page per function just for those additional informations. And as soon as we have one page per function, we can categorize them. The only impact of wanting categories is that we always need to create one page per function rather than just create the ones where we actually have examples or comments to expose. This is because wikis build categories automatically according to "tags" you insert into a page.

I second Pazyryk's response and also thank you for going to the effort.

DonQuiche said:

Sure, this is actually something I wanted to try with test3.

Click to expand...

Ahh...there.
Okay, but I meant not with the additional info in other pages, but all the necessary stuff in that one.

DonQuiche said:

Interesting, I didn't see such an example. Could you show me one please?
Now this is also something I thought about but I wasn't sure about it, hence why I would like to see an example.

Click to expand...

Oh, I guess a missunderstanding: They are NOT in the wiki.

DonQuiche said:

Other things I imagined are:
* Cross-pages categories, so that you could quickly see all resources-related functions, whether they are in City or in Plot
* One global index: sometimes it's useful.

Click to expand...

I guess the former would involve too much work.
+1 for the latter.

DonQuiche said:

PS: Is there a way to flag a page for auto-deletion? Or should I add those to a dedicated category? Do you have some way to quickly delete 1k pages for example (I won't generate them if you cannot delete them in a batch)?

Click to expand...

You'll have to ask deanej about that. He's currently the only person with beaurocrat level in the wiki (I'm just a normal user there).

The_J said:

Ahh...there.
Okay, but I meant not with the additional info in other pages, but all the necessary stuff in that one.

Click to expand...

So you mean either something like the 2k style or Test2, but with categories?

And regarding categories, do you think it should be small categories like in Categorized listing or fewer and broader categories?

You'll have to ask deanej about that. He's currently the only person with beaurocrat level in the wiki (I'm just a normal user there).

Click to expand...

Ok, I will contact him, thank you.


EDIT: I forgot you also wanted an array. I am quite skeptical about an array that would include every information but...

Here is the preview for the TerrainID page.

In the 2k wiki, the LUA enumerations "TerrainTypes", "CivilizationTypes" etc, were used as types in the functions' signatures. This was confusing because those parameters actually expect an integer for the corresponding ID column, not a string for the type column.

So instead I introduced TerrainID, CivilizationID, etc pseudo-types. Each of them get his own page that connects the TerrainID pseudo-type, the TerrainTypes LUA enumeration, and the Civ5Terrains data table together. There would be no page for the TerrainTypes enumeration, instead the home page would link directly to the TerrainID page. Note that the whole page is automatically generated, including the examples.

The_J said:

Ahh...there.
Okay, but I meant not with the additional info in other pages, but all the necessary stuff in that one.

Click to expand...

I just gave it a try: Test7.
Well, I am not fond of it. When compared to Test3 or Test8 for example, it is far easier to browse #3 and #8, and I do not think the parameters' comments are worth it: imho they're typically an information that ought to be only displayed in the detailed page of every function and not in the functions listing.

Test7 looks fine to me. I may have missed something in the discussion above, but is it possible to have a "contents" list at the top with links to these fuller entries below (like 2kgames wiki)? (Test3 and 8 were empty when I looked at them.)

A point of correction (tangential to the current discussion so I put in spoiler):

@Pazyryk
Unfortunately, I don't think it is possible with this kind of presentation (I guess one has to use standard section headers for the TOC to include them) but I will run some tests. So for you the best layout so far is the test7?

And thank you pointing out that mistake, I will fix that.

Some of the tests are now empty (3 & 8), so I can't evaluate all.

But what I'm trying to describe is a combination of Test2 and Test7. I.e., you have a "Contents" section like Test2. When you click on a method, it does not take you to a different page, but takes you "down-page" to a full description that looks like your layout in Test7. (I think you might be telling me this is difficult or impossible, but I'm not sure.)

95% of the methods don't need any explanation beyond the signature. So having links to 100s of empty pages seems kind of inelegant. It also makes user contribution feel...well...a little daunting. I'd be happy to contribute explanatory text or example usage for a few methods -- for some that are unclear or took some effort to use successfully (or indicate those that don't work at all). But faced with 100s of "red links" to empty pages, I feel like I'm going to be dragged into some giant accounting effort that I'd rather avoid.

The only problem I see with Test7 is that you have many signature and return values that don't need any explanation, and won't ever get them unless we have some OCD modders here (my apologies to anyone with OCD, no offence intended). So perhaps 70% of the text here is just clutter. Unfortunately, since this is automated it's probably all or none.

Synthesizing my rambling above, I guess what I really would like is Test2, but with the option to add text below the function (not via page link). Whoever enters text here can supply what is needed, which may be explanation of args, example usage or something else.

Pazyryk said:

Some of the tests are now empty (3 & 8), so I can't evaluate all.

Click to expand...

For some unknown reasons, they disappeared and then reappeared.

But what I'm trying to describe is a combination of Test2 and Test7. I.e., you have a "Contents" section like Test2. When you click on a method, it does not take you to a different page, but takes you "down-page" to a full description that looks like your layout in Test7.

Click to expand...

The only problem I see with Test7 is that you have many signature and return values that don't need any explanation, and won't ever get them unless we have some OCD modders here (my apologies to anyone with OCD, no offence intended). So perhaps 70% of the text here is just clutter. Unfortunately, since this is automated it's probably all or none.

Click to expand...

Here is the result: test10
At this point you probably think it's not: you also wanted the detailed informations when available, didn't you? But this is the point: they are never available on this whole page! So if we hide the clutter, then we get a flat list as the one you see. And at this point, the list itself is so compact that it becomes redundant with the table of contents.

So either we keep the clutter in and then it's just test7 + a toc, with a twenty kilometers long page full of clutter. Or we remove the clutter and the natural conclusion is test4.

Synthesizing my rambling above, I guess what I really would like is Test2, but with the option to add text below the function (not via page link). Whoever enters text here can supply what is needed, which may be explanation of args, example usage or something else.

Click to expand...

But test2 already includes that (you do have "edit" labels on every section). Do I misunderstand you or did you not see it? Now the problem is that it is hard to edit since the user have no template to copy.

95% of the methods don't need any explanation beyond the signature. So having links to 100s of empty pages seems kind of inelegant. It also makes user contribution feel...well...a little daunting. I'd be happy to contribute explanatory text or example usage for a few methods -- for some that are unclear or took some effort to use successfully (or indicate those that don't work at all). But faced with 100s of "red links" to empty pages, I feel like I'm going to be dragged into some giant accounting effort that I'd rather avoid.

Click to expand...

Actually every function page would be created, although they would be mere templates for the most part. I agree it is inelegant but it provides some benefits:
* Those pages are easy to edit since the template is already here. The clutter is present but only on the functions pages.
* We can easily create thematic categories by tagging those pages. this allows the creation of a global index and thematic cross-types indexes (all function for resources in the API for example).
* The links are not red anymore. And if we want to emphasize functions pages with actual user-provided content, we could just add one or two icons on the right side of the function signature in the listings.
* One page allows long examples. Those ones are hard to insert a single big page.

EDIT: here is a sample of a function page: test9

I guess that's fine. I just want some kind of quick visual cue that the method does what it appears to do and I need not look further, which is the case for 95% of them. The red link is perhaps a clue but a flawed one (some overly-eager modder might decide to add helpful comments to everything). The icons idea sounds great though. I could imagine two important icons:

(!) Known or suspected not to work.
(*) Non-intuitive usage.

The latter is somewhat subjective, but I doubt it would be overly used in a bad way. An example would be Map.Areas(), which you might guess iterates over either pArea or iArea (the value returned by plot:GetArea()), but does neither.

---------

Just a comment on your data type notation:

I like that you are consistently using "buildingID" to mean row ID (int) and "buildingType" to mean row Type (string). However, how are you handling unit object index (the value returned by unit:GetID())? I always use unitID for the table row and unitIndex for the object index, but Firaxis freely mixes the two, making it impossible to derive a standard that is consistent with the method names.