Mod-Header Discussion (PLEASE READ)

[ssilk]

To be honest: I was a little bit overrun with this mod-compatbility change: As soon, as I realized it, I immediately saw, that it would be the right time to break with all the old mod-stuff and begin a new. I still think this decision was right and the overwhelming number of mods using the new subboard-structure with success is in my eyes a good sign.

But on the other hand I had really only very little time to prepare everything ... and I made of course some mistakes. One of the mistakes was, that I declared to use a Mod-Description-Template (https://forums.factorio.com/forum/vie ... 89&t=13493) without discussion.

I want to catch this up now.

So I move the discussion with Dysoch into this thread. I hope for some more critics and input (and sorry for those, who put much afford into their headers.)

[ssilk]

MOD NAME OR PICTURE

Description:

• A small description about the mod

Details:

• Factorio Version: 0.12
• Released: July 18th 2015
• Dependencies: None (OPTIONAL!)
• Website: WEBSITE URL (OPTIONAL!)
• License: LINK TO LICENSE
• Tags: MAYBE? (if find tags not really important, since we have tagged mod subforums)
  

Download
Download Link

LONG DESCRIPTION

Here is the long description, not really needed for Big mods with their own forum, since they can make a new topic about it

CHANGLOG

Here is the changelog, not really needed for Big mods with their own forum, since they can make a new topic about it

Hm. This looks of course much nicer than https://forums.factorio.com/forum/vie ... 89&t=13493
I really think I like it.

But this will make problems: it's much more difficult to parse, especially it has no clear systematic (and blue as text-color is not readable in Factorio design).

And well, that was my main stake: To have this machine-readable.

Well, it is good enough to rethink the idea of the current template ( https://forums.factorio.com/forum/vie ... 89&t=13493 ). I think the essential part is the header and the rest is just how someone likes to do it.
So this is the revisited header as I currently would exchange:

Mod-Info-Header

• Name: Fancy transports
• Version: 1.0.2
• Factorio-Version: 0.12.0 (which Factorio version this was tested with)
• Description: Adding some UI stuff for transportation <(max. 140 chars)
• License: Link to a license or very short text description <(max. 140 chars)
• Release: 2015-07-23 (Year-Month-Day)
• Download-Url: Download (even when you uploaded it into this forum)
• Website: [url]http://some%20project%20page[/url] (even when there is only this article in forum, submit this article, then edit and add the url of this article)
• Dependencies: Optional. Names of dependent mods.
• Category: Optional. (One of Alpha, Helper, Item, SimpleExtension, Gameplay, Convenience, Compilation, CompleteOverhaul, ModPack, Lib, Other)
• Tags: Optional. Free, comma separated (E. g. Textures, User-Interface, Vehicles, fancy tag name)

as code:

Code: Select all

[size=150]Mod-Info-Header[/size]
[list]
[*] Name: Fancy transports
[*] Version: 1.0.2
[*] Factorio-Version: 0.12.0 (which Factorio version this was tested with)
[*] Description: Adding some UI stuff for transportation <(max. 140 chars)
[*] License: Link to a license or very short text description <(max. 140 chars)
[*] Release: 2015-07-23 (Year-Month-Day)
[*] Download-Url: [url=http://Direct-download-Url]Download[/url] (even when you uploaded it into this forum)
[*] Website: [url]http://some%20project%20page[/url] (even when there is only this article in forum, submit this article, then edit and add the url of this article)
[*] Dependencies: Optional. Names of dependent mods.
[*] Category:  Optional. (One of Alpha, Helper, Item, SimpleExtension, Gameplay, Convenience, Compilation, CompleteOverhaul, ModPack, Lib, Other)
[*] Tags: Optional. Free, comma separated (E. g. Textures, User-Interface, Vehicles, fancy tag name)[/list]

Everything else below this line is optional and it can follow any format, good practice will show us the right way.

I'm very open and would apreciate any suggestions and discussions about this.

[keyboardhack]

I have a few questions regarding the template.

What is "Release" used for? is it the date of the initial release of the mod? Is it for the newest release?
Why the limit of 140 chars?
What if you have more than one download url?
Maybe a but unrelated but there should be a texture mod subforum and a libary subforum as they don't really fit with modpacks.

I definetely think there should be somekind of template making it easier to grasp what a mod is about but i don't think it should be machine focused as i think it's mostly people who look at mods . I Understand that it will make it easier to search for a specific kind of mod, but i don't think that is worth it if human readability is lost in the process.

[DaveMcW]

And well, that was my main stake: To have this machine-readable.

The primary purpose of a forum is to be human-readable. Every day you delete spam-posts designed for machines to read (and thank you! ).

I think the minimal requirements slpwnd posted are enough. If a mod is popular enough that its users care about every new release, the author can add that info. But it is just distracting for someone looking for new mods.

A better goal for machine reading is to download the mod.zip and extract info.json. This can be automated without bothering mod authors and users.

[Choumiko]

While i initially was all for the Header as suggested by ssilk, i start to find that it's not looking good for us puny humans.
The one Dysoch suggests looks good, it's fairly structured but also looking good. If we really want/need a machine readable info it could go in one spoiler at the bottom and done.

I'm mostly interested in Factorio version required, what the mod does, latest release (version + date) and changelog/known issues. Only when i want to edit/continue/fix a mod i'm interest in the license, homepage/github.
Maybe instead of requiring a specific layout, simply require the minimum amount of information and leave the rest to the author?

A better goal for machine reading is to download the mod.zip and extract info.json. This can be automated without bothering mod authors and users.

Good point

[ssilk]

What is "Release" used for? is it the date of the initial release of the mod? Is it for the newest release?

Indeed.

Why the limit of 140 chars?

This is the short description. You need to limit a short description somehow, otherwise it is just a description. But the description can follow.

What if you have more than one download url?

Make a list, comma separated.

Maybe a but unrelated but there should be a texture mod subforum and a libary subforum as they don't really fit with modpacks.

It depends on standpoint. A modpack is also a mod (or it can be seen as such), but it has dependencies.

I definetely think there should be somekind of template making it easier to grasp what a mod is about but i don't think it should be machine focused as i think it's mostly people who look at mods . I Understand that it will make it easier to search for a specific kind of mod, but i don't think that is worth it if human readability is lost in the process.

Well, the plan I have in mind when I planned it, was to have a scanner, which reads this and automatically creates an overview-list.
With the format Dysoch described, this is much more difficult, than with my originating format. Which looks ugly.

So, I'm looking for some kind of compromise.

A better goal for machine reading is to download the mod.zip and extract info.json.

This is a good point. Most info's can be found there.

This can be automated without bothering mod authors and users.

Not completely. Many authors don't link the download directly. That makes automated scanning complex.

I'm mostly interested in Factorio version required, what the mod does, latest release (version + date) and changelog/known issues.
...
Maybe instead of requiring a specific layout, simply require the minimum amount of information and leave the rest to the author?

Yes. I think this is the way to go.

This would mean, we can go a bit more into Dysoch's suggestion:


MOD NAME OR PICTURE

Description:

• What this mod does or is used for (<140 chars)
• Latest-Release: v1.0.2, 2015-07-23 (Year-Month-Day)
• Required-Factorio-Version: 0.12.0
• Download-Url: Download (even when you uploaded it into this forum), Optional Download#2 (for more links separated by comma)
• Dependencies: Optional. Names of dependent mods. This list can be very long for modpacks etc.

The rest is optional, like
Version History:
...

Long Description:
...

etc.

[ssilk]

I've made an example mod: https://forums.factorio.com/forum/vie ... 91&t=13835

I think it shows, how that will look like.

Opinions?

[Zeblote]

Is there a point in having MOD in the title in a board full of mods?

[DaveMcW]

MOD NAME OR PICTURE

Description:

• What this mod does or is used for (<140 chars)
• Latest-Release: v1.0.2, 2015-07-23 (Year-Month-Day)
• Required-Factorio-Version: 0.12.0
• Download-Url: Download (even when you uploaded it into this forum), Optional Download#2 (for more links separated by comma)

Mod name or picture - already in the thread title
140 character limit - just stop reading after 140 characters if it is too long
Latest release number - already in info.json and the zip filename
Required factorio version - already in the thread title
Download url - already in the attachment, if hosted on the forum

It is not possible to read the release date directly, but there are ways to calculate it. Look at post edit date, or have a bot scan frequently for changes.

The only thing really required is a direct zip link, for files hosted somewhere else. A bot should be able to find this anywhere in the post.

Is there a point in having MOD in the title in a board full of mods?

Yes, for search results.

[Zeblote]

Is there a point in having MOD in the title in a board full of mods?

Yes, for search results.

Can't you just do this?

[DaveMcW]

I meant when you search the entire board, and end up in the mod section by accident.

[SHiRKiT]

Remember that some stuff here mat be GUIDES, other may be LIBRARIES, and other may be MODPACKS and so on, so I think it's worth to put MOD on title.

[ssilk]

Mod name or picture - already in the thread title

I thought it looks just a bit better to repeat this in big here.

140 character limit - just stop reading after 140 characters if it is too long

I changed it in the example mod: https://forums.factorio.com/forum/vie ... 122#p93122
No absolute limit here anymore, but 140 chars is just long enough for one line.

Latest release number - already in info.json and the zip filename
Required factorio version - already in the thread title
Download url - already in the attachment, if hosted on the forum

As a player I really would like to have that information in one place.

And for the download url: What to do, if one offers to download all previous versions? An automatic scanner cannot know, which is the right version to download.

It is not possible to read the release date directly, but there are ways to calculate it. Look at post edit date, or have a bot scan frequently for changes.

This is the same: It needs to read the whole thread and look, for the latest update. How should an update look like? That makes automatic scan really ugly.

The only thing really required is a direct zip link, for files hosted somewhere else. A bot should be able to find this anywhere in the post.

As said: This "anywhere" can be many.

Is there a point in having MOD in the title in a board full of mods?

Yes, for search results.

Agreed, this is needed. Perhaps we have at some point also MAP, SCENARIO or BLUEPRINT something like that. I introduced with my example also a BUGS https://forums.factorio.com/forum/vie ... 22&t=13836
But I'm really not sure, if that is a good idea. I just want to try this out, it was a suggestion from Betka.

[Zeblote]

You should also require every mod to have enough images in the main post to show what it does.

Let's pick a random mod to demonstrate: https://forums.factorio.com/forum/vie ... 92&t=13709
Even after reading all the irrelevant info in the topic, it's still not clear how a 'timelapse' actually looks. So what is the point? Do I have to install it to find out?? And how do I even use the mod???

If there's a mod topic and it's not clear what it does in less than a minute, most players will just close it.

[ssilk]

What you want to discuss is what's the best way to make a good mod-description.

What I want to discuss here is: What is essentially needed for describing a mod.

That is a completely different interest. I want to discuss this, cause it is my job as moderator/admin to look around and try to find ways, how to use the information in this forum better.
I don't have the interest to "sell a mod to players". That is completly the interest of the modder. Or eventually the devs (but also from a completley different point of view).

I mean it should be clear for every modder, that a mod needs good descriptions. Pics. Otherwise the whole work he puts into it is "for the cat" (how we say it in Germany). Maybe it is in the interest of the players to have much pics in the mod-threads.

I don't say, don't discuss it. I say: Do it! But I say also: Don't mix both interests.

Make for example another thread about it. I will support any descision made there.

[Narc]

Mod name or picture - already in the thread title

I thought it looks just a bit better to repeat this in big here.

I'll be honest, I totally missed it the first few times I looked at the example. The best I can say about it is, while it triggered my auto-ignore filter, it doesn't really get in the way much. On the other hand, it also doesn't seem to add much.

Latest release number - already in info.json and the zip filename
Required factorio version - already in the thread title
Download url - already in the attachment, if hosted on the forum

As a player I really would like to have that information in one place.

Definitely with you on that -- when I'm scanning my saved list of linked threads, it's nice to have all the immediately relevant information in one place, up front. That said, I am not a fan of the hyphenated words, as seen in the example. Even a bot should be able to match the string without the hyphens.

It is not possible to read the release date directly, but there are ways to calculate it. Look at post edit date, or have a bot scan frequently for changes.

This is the same: It needs to read the whole thread and look, for the latest update. How should an update look like? That makes automatic scan really ugly.

I don't think this question was ever asked: why would you want a bot to do this, and who's going to write it? If you want to be feeding a site that has all the mods in one place, why not switch away from the forum and make the site the primary upload location? You could still have forum threads automatically created for discussions.

in other words, I think you might be going about this in the opposite direction from how it normally goes.

[ssilk]

A bot will have no problems with the hyphens, that is really not much to look about this.

And to the last question: I have reasons.

And it gets now off-topic, but I think it is a point, I need to throw in now:
In June I have been in Prague with the dev-team and we talked half a day about a mod-plattform. Modding community. Call it whatever.

We looked at existing solutions. I think we looked at more than a dozen sites, which enables downloading.

And I found one thing, which is quite interesting: With an active modding comunity you need also the possibility to discuss mods.
There are two possibilities then:
A) Create a modding plattform, that also has some kind of mini-forum per mod.
B) Use and existing forum.

A seems to be the right way, but it is also the way with the most work. B on the other hand will look a bit crappy, but it will work without much changes to an existing solution and it is super flexible in how a modder creates his "area".

So the logical solution is, that I now prepare the forum for B. Making it like so, will enable to have very small steps of development. Which lowers the hurdle for changes.

[SpeedDaemon]

What about having the mod authors (or whoever wants to, really) explicitly submit their info.json to something like KSP's CKAN?

Seems like trying to format a machine-readable entry on a forum, and then creating something else to go dig the information out again to put in a database is a lot of unnecessary effort...

[Narc]

A bot will have no problems with the hyphens, that is really not much to look about this.

A bot will also have no problems without the hyphens, and the hyphens look bad. That is what I said.

[...]
There are two possibilities then:
A) Create a modding plattform, that also has some kind of mini-forum per mod.
B) Use and existing forum.

A seems to be the right way, but it is also the way with the most work. B on the other hand will look a bit crappy, but it will work without much changes to an existing solution and it is super flexible in how a modder creates his "area".

Yeah... except forums are lousy to begin with. And the "super flexible" thing is exactly what you're aiming to remove so that the entries are machine-readable. I have an idea: how about we put all the machine-readable parts in a spoiler that nobody has to open? It's still part of the post, technically, but it doesn't look ugly as sin.

A "modding platform with a mini-forum per mod" means "a site to upload files to, showing some meta-data about the files (some of which can be automatically derived from the files themselves), and linking to a forum thread". None of that is difficult, and it's a one-time setup instead of requiring posters and moderators to be careful about how the magical first post in a mod thread gets formatted.

What about having the mod authors (or whoever wants to, really) explicitly submit their info.json to something like KSP's CKAN?

Seems like trying to format a machine-readable entry on a forum, and then creating something else to go dig the information out again to put in a database is a lot of unnecessary effort...

Yes, that's basically what I meant about doing things backwards.

To the extent that forums are good for anything, they're good for discussions within large groups of people. Trying to bash them into a form that makes them good for something else is likely to take longer than doing the right thing in the first place, as well as being more fragile and unfriendly.

[ssilk]

A bot will have no problems with the hyphens, that is really not much to look about this.

A bot will also have no problems without the hyphens, and the hyphens look bad. That is what I said.

Ok, I removed it. How is that looking now: https://forums.factorio.com/forum/vie ... 91&t=13835

And the "super flexible" thing is exactly what you're aiming to remove so that the entries are machine-readable.

No, what I want to do is something, which helps to create the first database. After the first breakthroughs we will have a modding platform, where modders can add their mods, download, binary, sourcecode, links and all other essential information needed to handle a mod and also a link to the (essentially needed) discussions. Which is then this forum. Or at some point also somewhere else.
The target is to enable, that this forum-threads are eventually not longer needed, but also not needed to be removed, cause why removing a working system?

I have an idea: how about we put all the machine-readable parts in a spoiler that nobody has to open? It's still part of the post, technically, but it doesn't look ugly as sin.

Well, I don't have anything against that. But part of discussion is also, how to make both: machine- and human readable. I don't see the advantage in hiding it, cause for serious users this means to search for the hidden part and click on it, but maybe this is just my own opinion, cause I'm much more used to read such kind of texts, than the average reader.

Yeah... except forums are lousy to begin with.
... A "modding platform with a mini-forum per mod" means "a site to upload files to, showing some meta-data about the files (some of which can be automatically derived from the files themselves), and linking to a forum thread". None of that is difficult, and it's a one-time setup instead of requiring posters and moderators to be careful about how the magical first post in a mod thread gets formatted.
... To the extent that forums are good for anything, they're good for discussions within large groups of people. Trying to bash them into a form that makes them good for something else is likely to take longer than doing the right thing in the first place, as well as being more fragile and unfriendly.

I would count your critics as o. k. if you made a usable alternative suggestion.

The question is: What can be improved NOW to make things better than NOW?
Which means: This is of course a temporary state. We don't know, how long the current state will last. It can take a year. I don't calculate for that this year. Maybe after 0.13 release?
You are really invited to make it better.