Prototype Documentation

[voidc]

In the past some effort was made to document the prototype definitions. However, a lot of information is still missing and it is hard to keep the documentation up to date. In a recent post Rseding91 wrote:

The main problem with this is the same reason we haven't made any automated prototype documentation: There are So. Many. Different. Ways. that each bit of data can be provided for a given style and so many combinations of what it actually does that nobody has been able to make any auto-documentation system work.

Although I understand that an auto-documentation system would not be easy to implement, I still believe that something like it is the way to go. I wonder, how the Factorio team handles the complexity of the prototypes internally... For the modding community it would be hugely beneficial to leverage an exhaustive documentation not only of the scripting API but also of all the built in prototypes.

[Bilka]

However, a lot of information is still missing and it is hard to keep the documentation up to date.

Did you even see how the documentation used to look like? It's the most updated and complete it has ever been, partially due to me semi-automating it.

I wonder, how the Factorio team handles the complexity of the prototypes internally...

We look at the code.

[Rseding91]

The script API documentation can be found here: http://lua-api.factorio.com/

[rldml]

However, a lot of information is still missing and it is hard to keep the documentation up to date.

Did you even see how the documentation used to look like? It's the most updated and complete it has ever been, partially due to me semi-automating it.

Do you two talk about the same thing? I've been told earlier, that the prototype definitions are not the same as the lua-api.

To OP: Afaik Factorio loads and uses (most of?) his original prototype definitions as a mod, to be more clear: the "base"-mod.

This are just normal text files with definitions like you would write them by yourself if you write a mod with own objects and you can find them somewhere in the game-directory (i'm at work currently so i can't take a look into my personal computer right now) - but because there are a lot of entries you should invest some time to find what you're searching for.

[Bilka]

However, a lot of information is still missing and it is hard to keep the documentation up to date.

Did you even see how the documentation used to look like? It's the most updated and complete it has ever been, partially due to me semi-automating it.

Do you two talk about the same thing? I've been told earlier, that the prototype definitions are not the same as the lua-api.

Yes, we are both talking about the prototype documentation. Rseding however is talking about the lua api doc :)

This are just normal text files with definitions like you would write them by yourself if you write a mod with own objects and you can find them somewhere in the game-directory (i'm at work currently so i can't take a look into my personal computer right now) - but because there are a lot of entries you should invest some time to find what you're searching for.

That's not what the OP is looking for.The lua code you find in the files are simply tables. Which properties the game loads, what is optional and mandatory, what they default to and how it loads them can only be found in the c++ part of the game and on the linked wiki page. That information is what the OP is looking for.

I personally find it interesting that people still feel like the documentation is lacking so much. Most prototype pages only get around 10 views per month, so not many people are using it. So why do people still feel like the documentation is lacking, when they are not even using it?

[ratchetfreak]

That's not what the OP is looking for.The lua code you find in the files are simply tables. Which properties the game loads, what is optional and mandatory, what they default to and how it loads them can only be found in the c++ part of the game and on the linked wiki page. That information is what the OP is looking for.

I personally find it interesting that people still feel like the documentation is lacking so much. Most prototype pages only get around 10 views per month, so not many people are using it. So why do people still feel like the documentation is lacking, when they are not even using it?

because it's hard to find maybe?

[Godmave]

Possible reason for low usage: people don't find what they are looking for too often and disregard the wiki for that kind of lookup

I did not often search for prototypes, but when I did all I found in the wiki was a red link, meaning there is no page for that prototype.

[Bilka]

Possible reason for low usage: people don't find what they are looking for too often and disregard the wiki for that kind of lookup

I did not often search for prototypes, but when I did all I found in the wiki was a red link, meaning there is no page for that prototype.

The prototype definition page has quite a lot of views, so I don't think that the other pages are hard to find, they are all linked there. Seems more like a typical case of "what I'm looking for is exactly what is missing" and "I looked 5 months ago and it wasn't there so I assume it's still not there instead of looking again".

[Godmave]

It's all good (for me). If I don't find something I just ask on discord

Things I might have searched for in the last month would be:
Prototype/GuiStyle
Prototype/Rail
Prototype/TrainStop

But since I don't even remember that, it is not in the least important for me.

[eradicator]

So why do people still feel like the documentation is lacking, when they are not even using it?

Without wanting to diminish your work, from personal experience my main problem with the wiki is, that it is a wiki, and not a documentation. It has lengthy examples meant for beginners which i don't need. And the formatting is generally not very readable to me. Also personally i always search through all the base game files before even going to the wiki, so the things i'm really interested in on the wiki are also the things most likely to not be there.

Let_me_walk_you_through_a_few_personal_examples

1)
http://lua-api.factorio.com/latest/Classes let's me quickly ctrl-f through the whole documentation. It is indented for subfunctions and has only the bare minimum technical details, ideal to quickly skim over. This is the page i go to when i need to know something in the API. Does the wiki have an equivalent?

Also the API doc is inheritely complete. I know if something isn't there it doesn't exist. This is not true for the wiki, and thus the wiki loses it's chance to be a "source of certainty".

2)
https://wiki.factorio.com/Prototype_definitions The whole first paragraph is basically a "how to use a wiki" tutorial. Wasting screen space and my time to skim over it to tell if it's relevant or not. The actual list has several readability problems:

• the "bulletin points" before each item conveys no information, and it is unclear why they have different shapes. the
• the word "Prototype" in front of every line feels redundant in a list of prototypes.
• every line lists the name of the prototype twice (presumably C-side and Lua-side?). I only need the lua name, but that isn't even linked.
• "red links" and normal links are mixed instead of having the red ones at the end (i know, sorting, but it's less readable)
• the subcategories start new alphabetical sorting, making the list viewed as a whole chaotically sorted.
• the tree structure actually makes it more difficult to read for me
• the whole page conveys nothing but the names of the prototypes

.

3)
Let's look at some actual pages:
https://lua-api.factorio.com/latest/Lua ... LuaControl
https://wiki.factorio.com/Prototype/Inserter
The wiki pages starts with a wiki-typical "contents" header covering half my screen, conveying no information. The API page has a short overview over names, output types and a brief description instead. In the wiki "mandatory properties" tells me almost the same thing as the contents header, and uses two lines each for it this time. Also redundant usage of the word "Type/Types". The API instead has a whole section of neatly indented function descriptions telling me what they do, and how they're used.

Writing this i get a whole new level of appreciation for how much time must've been invensted into the API doc...

TL;DR: What the wiki lacks is formatting, formatting, findability, brievity and formatting. Did i mention formatting? And i'm not sure a "wiki" type solution can ever fix this.

[Bilka]

snip

Thank you for that objective and detailed feedback, I will definitely consider it.

[eradicator]

snip

Thank you for that objective and detailed feedback, I will definitely consider it.

Thank you for being able to take feedback without killing the messenger, an increasingly rare trait these days. If you care i could probably list a few more things. But ultimately i think the optimal solution would be if the prototype documentation had exactly the same style and formatting as the API doc, making it instantly familiar to read to everyone who ever looked at the API doc and vice versa.

[Bilka]

So why do people still feel like the documentation is lacking, when they are not even using it?

Without wanting to diminish your work, from personal experience my main problem with the wiki is, that it is a wiki, and not a documentation. It has lengthy examples meant for beginners which i don't need. And the formatting is generally not very readable to me. Also personally i always search through all the base game files before even going to the wiki, so the things i'm really interested in on the wiki are also the things most likely to not be there.

...

TL;DR: What the wiki lacks is formatting, formatting, findability, brievity and formatting. Did i mention formatting? And i'm not sure a "wiki" type solution can ever fix this.

It's been a while, but I am working on improving the prototype documentation in exactly the points that you mention. I have been toying around with some things on the testing wiki and would like some feedback.
In particular, these are the pages that I worked on: https://testing-wiki.factorio.com/Prototype/Item, https://testing-wiki.factorio.com/Prototype/Tool and https://testing-wiki.factorio.com/Prototype/Armor. The biggest change in the frontend should be the new properties overview at the start of the page, including inherited properties. I hope you can see that a lot of work went into that, but I'd like to know what to improve before I convert the main wiki to this system. So, please take a look and let me know what you think :)

If the site is down (has technical difficulties), shoot me a PM, I need to regularly reboot the server because it runs out of RAM. My testing ground just isn't a priority for a good server :p

[eradicator]

You put me in a shitty position where i'm sure i'm only gonna say negative things again (plus/minus notation). Also i'm pretty sure i'm a niche audience of the wiki, even though i've used it a fair bit more since the last time i commented in this thread. So,... i hope you realize you just asked the "grumpy old German man" for feedback *cough* *cough*. I'll write this as an unsorted stream of thoughts which hopefully will somehow magically be more useful than writing it properly :p.


Prototype/Item

• (+) Getting rid of the sub-indexes looks nicer
  -> less clutter
• (-) linking the types in-line in the content table (edit: opinion changes below... :p)
  -> makes it more difficult for me to quickly eyeball-scan for the thing i'm looking
  -> the api has it formatted as a table so i can scan rows independantly.
  -> wait... did i really complain about this? -> rechecks -> yes i did *sigh*
  -> /me does side-by-side comparision
  -> /me notices it looks like the api now, so why does it look bad
  -> So i think the main difference between the new content table and the api is that (unfairly) all the clicked links on my api page have a different color because the browser marks used links. And maybe because the api doesn't bother with having "Types/" before everything, because if it's literally before everything then it's redundant.
  -> /me clicks around a bit to "change the link color"... the longer i look at it the better it looks
• (?) Basics/Extensions not linked at all? (personally don't care, but feels "incomplete")
• (?) Rest of the page looks unaltered
• (-) Rest of the page still has no indentation between sub-header and paragraph content. I.e. shouldn't everything except the property_names (in bold beige) be indented one level?

Prototype/Tool

• (+) definetly getting used to the new properties style while looking at it... :)
• (?) Basics/Extensions not linked at all? (see above)
• (++) The "inherited from" section is really nice
  -> though i was a bit confused that the dialogue now links to stuff on another page (but so does the api, so just another "needs getting used to" thing)
• the api styles "(optional)" in lower-case and mandatory is the default implication. fiddled a bit with the html, and i definetly like that better then the unstyled Capital Letters version.
  -> experimented by styling "mandatory" and "(optional)" is also not that bad with using the "common-sense" meaning of brackets implying optionality, but if possible i think i still prefer "mandatory" not being mentiond at all. your mileage will vary.

Prototype/Armor

• (+) the reduced spacing in the "optional properties" section between the "Type:" line and the description line is a nice addition (reduction :p?). But i do think some additional indentation... *cough* (see above).

[Bilka]

So,... i hope you realize you just asked the "grumpy old German man" for feedback *cough* *cough*.

I appreciate any feedback I can get :) I gotta applaud you though, somehow you managed to look at the pages before I completely fucked their style.

"Rest of the page still has no indentation between sub-header and paragraph content. I.e. shouldn't everything except the property_names (in bold beige) be indented one level?"
Somehow I completely missed this in the first feedback post, it's a really good point. Fixed. But only partially. Does that make it any better? I like it.

"Basics/Extensions not linked at all? (personally don't care, but feels "incomplete")"
Any idea where it would fit? It's obviously not part of the properties, but weird to exclude. One suggestion was to keep it how it is now and to make the "inherited properties" section and the "extension" collapsed by default. That way they should not be in the way as much, and it feels less important to link them.

I changed a whole bunch of things, please take a look again.

PS:
"Rest of the page looks unaltered" No idea what I should change about how properties are presented beyond the indentation.

[tiriscef]

Something that annoys me when I use the wiki: I'm always missing a link back to the 'Prototype definitions'-overview-site. Maybe that's just me having a weird workflow, but I'm often visiting this site when I'm trying to find infos about another prototype.

[mat1k]

Something that annoys me when I use the wiki: I'm always missing a link back to the 'Prototype definitions'-overview-site. Maybe that's just me having a weird workflow, but I'm often visiting this site when I'm trying to find infos about another prototype.

I hear that. I've taken to keeping the main page open in a seperate tab and just opening the definitions i want in new tabs so i don't lose the main page.

[eradicator]

Me looks again at: https://testing-wiki.factorio.com/Prototype/Item

? The description is *not* indented, only Type: and Default: are. That looks weird to me.
- I don't like the dotted lines. They waste screenspace again, and are kinda floating...ish, comapred to the previous "box" style. (And i think they just have an irritating effect on my eyes due to how small the dots are.) (/me goes to compare with api doc: aha! Due to your dotlines being white they have a higer contrast to the background than the text itself, while on the api they're barely noticable.) Also yours have significantly more spacing (i don't like spacing, i only like SPAAAACE.)

contrast.png (16.4 KiB) Viewed 3340 times

? Also comparing api <-> wiki i just noticed that you've got "the wrong type of gray" ;). And use yellow instead of orange. (never noticed before, but now i can't unsee it /jk)

? Description placeholder...do you intend to make the whole block wider? Otherwise there's really not much space. Also if the description is already in the top panel, then 99% of the page content is in the top panel. Would be closer to the api though...dunno.

? Basics/Extensions dunno, they look fine where they are now so just ...link them at the top of the page? Extensions isn't really..hm..relevant? related? to the behavior of the "parent" so putting them into the main content table would imho be weird. On wikipedia i think this type of info would be at the bottom of the page as "See also". Honestly i've never looked at it. While i'm interested what a prototype is inherited *from*, the opposite inheritations *to* are not needed very often (i extracted them once manually in data stage and hardcoded everything that's an "item" ;p). TL;DR: Dunno.

PS:
"Rest of the page looks unaltered" No idea what I should change about how properties are presented beyond the indentation.

That was just meant as a general "Did i miss anything else?" style comment on my side.

It's getting much closer to the "original" (api doc) though :D. Is there a "Classes" style master page yet?

[Bilka]

Something that annoys me when I use the wiki: I'm always missing a link back to the 'Prototype definitions'-overview-site. Maybe that's just me having a weird workflow, but I'm often visiting this site when I'm trying to find infos about another prototype.

https://testing-wiki.factorio.com/Prototype/Armor (and Tool and Item) now links all its parents at the top and to the overview site, so this should be solved.

? Also comparing api <-> wiki i just noticed that you've got "the wrong type of gray" ;). And use yellow instead of orange. (never noticed before, but now i can't unsee it /jk)

Says the person who uses their own custom "visited link" color :P

? Description placeholder...do you intend to make the whole block wider? Otherwise there's really not much space. Also if the description is already in the top panel, then 99% of the page content is in the top panel. Would be closer to the api though...dunno.

I ended up not putting the description into the top panel at all, it's now type + (optional) only. I hope that it still gives the desired overview.

I got rid of the basics section entirely, its content is now above the top panel, which works rather well for the "what is this even" information. I still have no idea what to do with the extensions :/

To the other two points: soon™ ;)

Anything you dislike about the "new" state? I've been thinking about how I should sort the "inherited from" sections of the top panel, so suggestions for that would be appreciated.

[eradicator]

? Also comparing api <-> wiki i just noticed that you've got "the wrong type of gray" . And use yellow instead of orange. (never noticed before, but now i can't unsee it /jk)

Says the person who uses their own custom "visited link" color

One of us missed the others sarcasm here. Not sure who .

Other than that, dunno. Does the "(optional)" look better in non-italic? Or am i allowed to make a post saying "it all looks fine (except for what i already said)" :p? Also pre-warning: Possible delays in answering-speed incoming during the next (few) weeks .