Friday Facts #294 - Blog thoughts & Lua documentation improvements

[Bilka]

...

Let's take a step back here. You linked a page with only read-only attributes and say that you want know what changing them does. Why would we document what a change does, when you cannot change something? It is wasted time and misleading.

The aim for the *Prototype pages on the Lua API doc page is to document the format and make sure that it is obvious what the "connected" property in the data stage is. The linked page does this rather well already by using the same name as the data stage properties, so no further explanation is necessary.

The wiki answered my question

As it should, because the wiki is the prototype documentation, and the page on there should describe what changing does - because it is about changing it. You have very valid points with information still missing from the wiki. It is something that I am working on, but documentation takes time and the "normal" wiki is higher priority than pages that no-one might ever use.

I recommend you to make a post the in modding help subforum whenever you want to know how a specific prototype property does. When someone wants to use a property, it means that it is always worth my time to spend 30+ minutes looking through the source code and writing a description for the property right then and there, so I will usually do so. Thus, you get your question answered and the prototype doc slowly gets better, with a focus on the useful properties. In case you are interested, here are past examples of such "documentation requests": viewtopic.php?f=34&t=69889, viewtopic.php?f=25&t=70098, viewtopic.php?f=25&t=69563, and viewtopic.php?f=25&t=70307 (yet to be documented).

[CodeZ]

The aim for the *Prototype pages on the Lua API doc page is to document the format and make sure that it is obvious what the "connected" property in the data stage is. The linked page does this rather well already by using the same name as the data stage properties, so no further explanation is necessary.

The wiki answered my question

As it should, because the wiki is the prototype documentation, and the page on there should describe what changing does - because it is about changing it. You have very valid points with information still missing from the wiki. It is something that I am working on, but documentation takes time and the "normal" wiki is higher priority than pages that no-one might ever use.

The separation of API (i.e. whatever the Lua code can access on runtime) and wiki documentation (i.e. whatever a mod can put in its data section (written in Lua **, though) and what the values mean) scopes seem to not be so clear here, especially as the API doc pages make almost no reference to the wiki (only references are Natural sort order-, and Log file -pages). Even if the prototype properties in API side are read only, reading them without knowledge of what should be expected is not too helpful.
I guess writing the prototype (etc) documentation both in API and wiki could be considered repetition and needless. Thus my suggestion would be, that the API doc would refer corresponding wiki page for further information. Then it would be something like "This is the (exact) API and what types different properties have. See *this wiki page* for detailed information how the values should be interpreted and how to declare data for this."

**) As the data is also written in Lua, some might think it as interfacing with the API. Thus reading the prototypes (or stuff that should be sought from wiki) from API seems to be natural first step.

[Deadlock989]

... In case you are interested, here are past examples of such "documentation requests": viewtopic.php?f=34&t=69889, viewtopic.php?f=25&t=70098, viewtopic.php?f=25&t=69563, and viewtopic.php?f=25&t=70307 (yet to be documented).

Sorry to create so much work for you

Just in case it slipped off the radar: viewtopic.php?f=50&t=69847

[Bilka]

The separation of API (i.e. whatever the Lua code can access on runtime) and wiki documentation (i.e. whatever a mod can put in its data section (written in Lua **, though) and what the values mean) scopes seem to not be so clear here, especially as the API doc pages make almost no reference to the wiki (only references are Natural sort order-, and Log file -pages).

The separation is rather clear "from the backend"; is separated by the stages. Combine that with the wiki links you mention, here is how it looks like now:

Sorry to create so much work for you

Just in case it slipped off the radar: viewtopic.php?f=50&t=69847

You are not creating work, just changing my priorities (to the better)

Yea, the ammo... Hopefully I will soon have a few hours to invest into it.

[Deadlock989]

You are not creating work, just changing my priorities (to the better)

Yea, the ammo... Hopefully I will soon have a few hours to invest into it.

I mean, it's lower priority for me personally now, I've figured 99% of it out, but it took me hours. Ammo definitions and attack_parameters are the most brain-curdling prototypes I've yet encountered. You can learn a huge amount from examining vanilla entities in your data.raw dump, but some of them just aren't visually intuitive - e.g. massively nested stuff like attack_parameters.

Also kicking myself because I only yesterday discovered that you can see how many of the vanilla entities are originally defined in the base's demo_entities.lua. Sometimes that's better than looking at the data.raw dump because often they are organised the way a person orders things, not in clinical alphabetical order.

What would have saved me a lot of time a while ago is if, for a particular parameter, the wiki mentions that the base "mod" provides some utility functions for working with it easily - e.g. for circuit_connector_sprites and circuit_wire_connection_points, there is a handy circuit_connector_definitions.create() function provided by base which just spits out everything you need given a variation and a simple pixel location, and stops you having to guess.

[CodeZ]

...
The separation is rather clear "from the backend"; is separated by the stages. Combine that with the wiki links you mention, here is how it looks like now:
...

Yeah, thanks, that's a step to better Although so, I'll add a side note as fluid boxes were the original case for Cadde: the fluid box prototype documentation lies in the Types/ -side and as such is not listed on the Prototype definitions page.

[Cadde]

Let's take a step back here. You linked a page with only read-only attributes and say that you want know what changing them does. Why would we document what a change does, when you cannot change something? It is wasted time and misleading.

I am sorry for the confusion. There are two places i tend to look when trying to figure out what a certain prototype property does. LUA API and the wiki.
To me, the two are interconnected even though prototypes cannot be changed in a live game.

As it should, because the wiki is the prototype documentation, and the page on there should describe what changing does - because it is about changing it. You have very valid points with information still missing from the wiki. It is something that I am working on, but documentation takes time and the "normal" wiki is higher priority than pages that no-one might ever use.

My point is that even a simple one liner describing a property beyond it's code name would be swell to people who are new to modding Factorio.

I recommend you to make a post the in modding help subforum whenever you want to know how a specific prototype property does. When someone wants to use a property, it means that it is always worth my time to spend 30+ minutes looking through the source code and writing a description for the property right then and there, so I will usually do so.

I commend your initiative. However i feel it could be handled differently.

When i decided i would take a stab at modding something in Factorio i looked at the thing i wanted to modify and was met with several not so simple question marks. A "normal" person would have just given up at that point. "Not documented, google didn't answer, CBA to make a post and monitor said post for a week to see if anyone comes up with an answer"

In my case, i was somewhat lucky in that all the mechanics were explained through rigorous testing by another player, but i had to mentally link the different effects observed to their respective prototype definitions and it took me a long time to actually figure out that flow rate was not just related to the "size" of the pipe but with each and every fluid as well.

Say you have some code that deals with base_area, base_level and the fluid viscosity. If one were to just add a comment in code for that one particular property with the formula used to determine flow it would have been massively helpful.
Add to this, base_area really doesn't tell a new modder much. Again, a comment stating "cross section of pipe, 1 = 100 units" would have made it much clearer and saved a potential new modder the trouble of digging around.

I am not saying you should go and document every single property out there in one go. But there are some core stuff (belts, inserters and fluids being three major ones) to the game that are quite likely to be modded by a, to be, modder.

And frankly, there are some things i've wanted to modify in the past but didn't because "i've already been there, took me that long to figure out fluids so i can only imagine how painful that would be".
Also, i am a very impatient person by nature, so i'd rather not ask. And i hate asking for things to boot.

As a counter example, i remember the days when looking at the MSDN to figure out how to use some class in .NET. They initially had very poor documentation but it eventually grew.
But what REALLY helped in the end were the "reference code" or whatever it was called. Instead of reading documentation, one could actually see the .NET sources for various classes.
Perhaps that's something to consider? Windows into the source code behind some core aspects of the game? It wouldn't just help modders, it would help regular players too!

[Impatient]

... when looking at the MSDN to figure out how to use some class in .NET. They initially had very poor documentation ...

Very friendly to call it "poor" how it was back then. It was almost useless and codeproject, stackoverflow and usegroups were the places to get information. After years, during which they managed to improve the usefulness just slightly, they finally understood how valuable user contributions are and they opened their documentation system to the users. Or maybe just because out of desperation.

The thing is, a developing company - including their documentation writers - always has a different view on the code and the documentation system it provides than the users. It is just natural. And that fact can not be changed. Only users fully understand what users want and need.

[Qon]

Apparently "input" means "output" and vice versa, but only sometimes! And it's not documented! And it is "not a bug"?

Can we at least get the meaning of "input" and "output" documented for each case where those words are used so we don't have to guess? Would be even better if they meant the same thing as in a dictionary instead of the opposite in my opinion. But apparently, even internally consistent definitions that don't flip around in some places is too much to ask for.