Documenting Mods and Add-ons

[Wolf Baginski]

It has, I confess, been annoying week. One or two mod developers have already heard specific comments, sent direct. I have puzzled out a couple of things, but some of you guys can be more than a bit obscure.

So I thought I'd try to make some helpful suggestions, rather than just ranting.

1: Building in help features is a good thing. But remember that the new user may not be starting quite where you expect. For an example of where this can be a needless puzzle, got look at the Wiki page at http://wiki.kerbalspaceprogram.com/wiki/Subassembly Ask yourself this. How do I make and store a sub-assembly? I had to do a lot of digging, in a maze of twisted forum posts, all alike, before I found a mention that you needed Advanced Mode. I eventually found that: click on the icon at the top-left of the VAB screen, an extra row vertical of icons appears at the left, and one of these switches to the sub-assembly mode.

2: When you have a Mod pack with a large number of parts, a list is helpful. Plain text is good, with the part-categories. Some part details are more useful than others. For a fuel tank, diameter and capacity. It's worth knowing the thrust of an engine.

3: For the more complicated items, has some key detail been missed? Be careful of revisions. There is one useful utility that does one job in two distinct steps. There's a primary window, and you have to use sub-window A to get to the target planet, before the useful semi-cheat in sub-window B. There was a helpfile in an earlier version, and I was able to read the source, and this was mentioned. It isn't in the current system.

4: It's probably useful for you as an author too: include a readme.txt file which details what the Mod does. Include which KSP version it is made for. Some Mods have dependencies. List them. Sometimes a Mod might not depend on a particular item but you won't get the full effect without itâ€â€you can do things with the Tech Tree, but Rockomax-sized boosters need Rockomax-sized tanks.

None of this needs great literature. But. as with so much else in the world, the bottom 10% can be really bad, and not difficult to fix. I have seen a few related things in part.cfg files, such as description texts with a spelling error, and a decoupler labelled with the wrong size. That sort of error is why even professional authors have to deal with copy-editors. Believe me, you can be uncannily blind to your own errors. "Just Read The Instructions" is a great name for a ship to land rockets on, but somebody had to write the instructions.

[Stone Blue]

I agree with everything above. But its hard enough just to get people to standardize the title of their mod relese threads...ie should have the current version of KSP supported, latest date of the release, and a clear, concise name of the mod. For example some mod names are one thing in the thread title, called another name in the thread, and then the name of the .zip file is something different, sometimes with "_" or other non-standard characters, and no version number...

THEN, add in, some people still dont follow the "standard" folder structure...

[michaelhester07]

I'm guilty of the folder inside not matching the zip or the mod name. I've started using my own "company" folder though. I do try to keep a catalog of parts and the mod description documents most of what you need to know. There really is no sticky "standard" for mod structure though.

[Dazpoet]

In my experience very few people say no to some help. If people have their mods on github ask them to open up the wiki and maybe you can add stuff to it. If their mods are hosted elsewhere write an example of what you think is missing and ask the modcreator to consider adding it to their post?

[nightingale]

Also, I no longer trust that wiki - I see so much that is out of date. For the subassemblies, the page in question was last updated before 0.90 came out. Back in 0.25, the subassemblies were in the "normal" list - you didn't need to go to advanced mode. So your issue there is with Squad making stock KSP unclear for that.

[rabidninjawombat]

In my experience very few people say no to some help. If people have their mods on github ask them to open up the wiki and maybe you can add stuff to it. If their mods are hosted elsewhere write an example of what you think is missing and ask the modcreator to consider adding it to their post?

I second what Dazpoet said =)

Remember most modders are doing this out of their love for the game, in their spare time, and for free. I would bet most of them would be more then happy to have a hand, especialy with documentation. =) .

[philotical]

I second what Dazpoet said =)

Remember most modders are doing this out of their love for the game, in their spare time, and for free. I would bet most of them would be more then happy to have a hand, especialy with documentation. =) .

I would..

[Justin Kerbice]

Good but unfortunately... too much modders are more interested to put a useless license file, sometime in many/every subdirectories of their GameData folder, than a single readme... or put changelog/revision history prior to any single explanation of what their stuff is all about .

(but it's not as worth as many GTA4 mods... no install instructions for most of the things there, just a few words and a stupid useless changelog)

Ok it's on free time but what the purpose of sharing (they surely like when people like their mods, right ?) if it's doing it a bad way ?

NOBODY knows what you know by doing something, so explanations are mandatory, or just don't share at all.

[Crzyrndm]

Good but unfortunately... too much modders are more interested to put a useless license file, sometime in many/every subdirectories of their GameData folder, than a single readme... or put changelog/revision history prior to any single explanation of what their stuff is all about .

Specifying the license is required by forum rules remember. As for a readme, it's just another set of documentation to keep up to date. One place is difficult enough to be bothered with.

so explanations are mandatory, or just don't share at all.

...

And that's just taking it too far