Difference between revisions of "Add-on etiquette"

Revision as of 10:08, 7 January 2008

This article is not meant as a set of rules which you have to follow by any means. It's more like a set of guidelines, which are meant to make your add-ons a bit more compatible to other add-ons and also make your life a bit easier when dealing with other developers.

The most important rule: Don't forget writing a manual

Even if you think using your add-on is the most trivial thing in the world - it usually isn't. A few lines about how to install and how to use it are sometimes enough, but they have to be there. Also make sure that somebody is able to read your manual. You have many (free) tools for creating good looking PDF format manuals. Use them. Don't put your documentation in Orbiter's root folder. There is a dedicated folder "doc" around for this task, but the folder "add-on docs" is also common. Don't name your manual "readme.txt". This file is often replaced soon by other add-ons.

Additionally, since Orbiter 2006, its possible to include compressed HTML files as online help for add-ons. This really makes it much easier to use your add-on, so its a good thing to do.

Don't violate the copyrights of other developers

You sure don't want for this to happen to you, and in most cases in our large add-on population, you can find very well done add-ons, which just want to be credited properly in your own credits, if you use them. Does it really harm somebody to write "These meshes were done by x y z"? No!

Don't make people install your add-on before they read the important notes

If you overwrite files or have special install instructions, let the user see the readme or the installation instructions first and then install it. That's especially important if you have special terms of use.

Don't overwrite files from Orbiter's base distribution

It's OK to include a line about how to put a base on a planet and let the player himself figure it out how to do this. But very often such modifications damage the base orbiter installation and make it impossible to run the default scenarios. You don't need to do this, so avoid it. If you replace a file from orbiter, make sure the add-on works with all default scenarios.

Don't overwrite files from other add-ons

It's almost impossible to check the meshes or textures of all released add-ons, but often add-ons overwrite files even of popular add-ons. Like Orbiter's basic files, other add-ons may no longer function if you start overwriting their files. The same may also happen to your add-ons - do you really want to risk this trouble?

Bug reports are good

Don't get angry if somebody reports only the bugs of your add-on instead of writing a good review. You did not find these bugs before releasing it, so it's your own fault that somebody can even post the bug reports. Also such bug reports are posted for improving your add-on, because somebody is really interested in it.

Use names and filenames that make sense

That's normally no big problem, but especially when two add-ons simulate the same historic vehicle, it may happen that both use the same parts and filenames.

@@ Line 1: / Line 1: @@
-This article is not meant as a set of rules which you have to follow by any means. It's more like a set of guidelines, which are meant to make your addons a bit more compatible to other addons and also make your life a bit easier when dealing with other developers.
+This article is not meant as a set of rules which you have to follow by any means. It's more like a set of guidelines, which are meant to make your [[Add-on|add-ons]] a bit more compatible to other add-ons and also make your life a bit easier when dealing with other developers.
-# The most important rule: '''Don't forget writing a manual'''. Even if you think using your addon is the most trivial thing in the world - it usually isn't. A few lines about how to install and how to use it are sometimes enough, but they have to be there. Also make sure that somebody is able to read your manual. You have many (free) tools for creating good looking PDF format manuals. Use them. Don't put your documentation in orbiter's root folder. There is a dedicated folder "doc" around for this task. Don't name your manual "readme.txt". This file is often replaced soon by other addons.
+==The most important rule: Don't forget writing a manual==
-# '''Don't violate the copyrights of other developers'''. You sure don't want for this to happen to you, and in most cases in our large addon population, you can find very well done addons, which just want to be credited properly in your own credits. Does it really harm somebody to write "These meshes were done by x y z"? No!
+Even if you think using your add-on is the most trivial thing in the world - it usually isn't. A few lines about how to install and how to use it are sometimes enough, but they have to be there. Also make sure that somebody is able to read your manual. You have many (free) tools for creating good looking [[w:PDF|PDF]] format manuals. Use them. Don't put your documentation in [[Orbiter]]'s root folder. There is a dedicated folder "doc" around for this task, but the folder "add-on docs" is also common. Don't name your manual "readme.txt". This file is often replaced soon by other add-ons.
-# '''Don't make people install your addon before they read the important notes'''. If you overwrite files or have special install instructions, let the user see the readme or the installation instructions first and then install it. That's especially important if you have special terms of use.
-# '''Don't overwrite files from orbiter's base distribution'''. It's OK to include a line about how to put a base on a planet and let the player himself figure it out how to do this. But very often such modifications damage the base orbiter installation and make it impossible to run the default scenarios.  You don't need to do this, so avoid it. When you replace a file from orbiter, make sure the addon works with all default scenarios.
+Additionally, since [[Orbiter 2006]], its possible to include [[w:CHM|compressed HTML]] files as [[Online help|online help]] for add-ons. This really makes it much easier to use your add-on, so its a good thing to do.
-# '''Don't overwrite files from other addons'''. It's almost impossible to check the meshes or textures of all released addons, but often addons overwrite files even of popular addons. Like orbiter's basic files, other addons may no longer function if you start overwriting their files. The same may also happen to your addons - do you really want to risk this trouble?
-# '''Bug reports are good'''. Don't get angry if somebody reports only the bugs of your addon instead of writing a good critique. You did not find these bugs before releasing it, so it's your own fault that somebody can even post the bug reports. Also such bug reports are posted for improving your addon, because somebody is really interested in it.
+==Don't violate the copyrights of other developers==
-# '''Use names and filenames that make sense'''. That's normally no big problem, but especially when two addons simulate the same historic vehicle, it may happen that both use the same parts and filenames.
+You sure don't want for this to happen to you, and in most cases in our large add-on population, you can find very well done add-ons, which just want to be credited properly in your own credits, if you use them. Does it really harm somebody to write "These meshes were done by x y z"? No!
+==Don't make people install your add-on before they read the important notes==
+If you overwrite files or have special install instructions, let the user see the readme or the installation instructions first and then install it. That's especially important if you have special terms of use.
+==Don't overwrite files from Orbiter's base distribution==
+It's OK to include a line about how to put a [[Surface base|base]] on a [[Planet|planet]] and let the player himself figure it out how to do this. But very often such modifications damage the base orbiter installation and make it impossible to run the default scenarios.  You don't need to do this, so avoid it. If you replace a file from orbiter, make sure the add-on works with all default scenarios.
+==Don't overwrite files from other add-ons==
+It's almost impossible to check the [[Mesh|meshes]] or [[Texture|textures]] of all released add-ons, but often add-ons overwrite files even of popular add-ons. Like Orbiter's basic files, other add-ons may no longer function if you start overwriting their files. The same may also happen to your add-ons - do you really want to risk this trouble?
+==[[Bug report|Bug reports]] are good==
+Don't get angry if somebody reports only the bugs of your add-on instead of writing a good review. You did not find these bugs before releasing it, so it's your own fault that somebody can even post the bug reports. Also such bug reports are posted for improving your add-on, because somebody is really interested in it.
+==Use names and filenames that make sense==
+That's normally no big problem, but especially when two add-ons simulate the same historic vehicle, it may happen that both use the same parts and filenames.
 [[Category:Add-ons|Add-on etiq]]