Every moron knows what should be in a Readme file, at least when you read one... Because you know exactly what you are looking for. Start to write one however, and you will be less certain of what to put in it. This tutorial tries to help by setting a loose standard for the contents of a readme file.

The purpose of a readme file for a *.pk3 is to answer any questions a person may have about the *.pk3. Remember that this person may be many different types: A player, a server administrator, a mod reviewer or maybe even a mapper like yourself.

If a section has no relevance for your mod: Don't include it just because it "should be there", but don't skip a section just because its boring to write!

The readme file I will produce here is for a map. Here is an example readme file, just copy it and change the stuff you need to...

1. Heading
2. Abstract
3. Index
4. Installation and UN-installation instructions
5. Core data
6. History / Strategy / Fun facts / About / Usage
7. Errors
8. Version history
9. Contact
10. Copyrights
11. Greetings

Heading

A descriptive heading.

Example:

Heavy water production plant at Vemork in Rjukan, Norway, February 1943

The abstract is a ( short ) summary of the contents of the file. Just 2 or 3 sentences will do. The abstract can be skipped if the there is little content in the readme file. In that case a descriptive heading may do the job.

Example:

>>>>>>>>>>>>>>>>>>>>>>>>> ABSTRACT <<<<<<<<<<<<<<<<<<<<<<<<<<< This map is inspired by a real WW2 operation executed in February 1943 called Operation Gunnerside. It was executed to slow or stop the Axis research into nuclear science.

The index ( or Table Of Contents ( TOC) ) can be skipped if the there is little content in the readme file. A rule of thumb is that you don't need an index if you can see the complete text at once ( one page of text ).

Example:

>>>>>>>>>>>>>>>>>>>>>>>>>> INDEX <<<<<<<<<<<<<<<<<<<<<<<<<<<<< - Installation and UN-installation instructions - Map data - History of Vemork - Other stuff that is neat to know - Known errors / problems - Reporting an error / problem - Version history - Contact - Copyright

A simple mod may have a very simple installation instruction. But in some cases a more detailed instruction may be needed. Most installations are only to copy a *.pk3 file to the main directory.

Example:

>>>>>> INSTALLATION AND UN-INSTALLATION INSTRUCTIONS <<<<<<<<< - To install the map, open up the zip file ( that you have already managed if you are reading this ) put the file user-vemork_factory_small_obj.pk3 into your /main directory. That's it! Go play! - To UN-install the map, remove the file user-vemork_factory_small_obj.pk3 from your /main directory. That's it!

This is a section containing the "hard facts" of the *.pk3. If you can answer a question very shortly, or with just a number: This is where it probably belongs. This is in my opinion the most important part of the readme file...

Example:

>>>>>>>>>>>>>>>>>>>>>>>>> MAP DATA <<<<<<<<<<<<<<<<<<<<<<<<<<< Map name : obj/vemork_factory_small Map type : Multiplayer objective Game support : Medal Of Honor Allied Assault(Untested in SH) # of players : 32 Version : 1.1 Release date : 2003-03-12 Map designer : Bjarne Grönnevik Map home page : http://www.planetmedal.com/rjukanproject Beta test crew: Clan "Friendly Fire is ON" http://ff.lmao.cc Compile flags : BSP stage: '-blocksize 0', VIS stage: Nothing extra, LIGHT stage: '-final'.

This section will probably vary a lot from mod to mod, some mods may have an interesting background that needs to be told, some maps may have been specially designed with a specific strategy in mind, a weapon mod may have a special use that needs to be explained. And then again: some mods may not need it at all.

Example:

>>>>>>>>>>>>>>>>>>>>>> HISTORY OF VEMORK <<<<<<<<<<<<<<<<<<<<< - This map is inspired by a real WW2 operation executed in February 1943 called Operation Gunnerside. Operation Gunnerside: 6 Norwegian elite soldiers in English uniforms parachuted over Hardangervidda, joined with the scouts, reached Våer, and approached the factory along the railroad tracks, an area that had no mines. While the rest kept guard, the demotions team entered the heavy water plant and destroyed the heavy water cells. 900 kg of heavy water was lost (including production losses). Afterwards the scouts remained on the mountain, while the demotions team went on skies into Sweden. >>>>>>>>>>> OTHER STUFF THAT IS NEAT TO KNOW <<<<<<<<<<<<<<<<< - The map is made up of a single, huge, five floor factory and a small outside area around it. - There are 3 objectives: 1: Blow the distillers on the 2:nd floor 2,3: Steal documents on the 4:Th. floor. - The map is rather large ( but smaller than its "father", obj/vemork_factory ) and you may expect not to know where the enemy is at all times, as there are many ways to approach the objectives. - If you get bored, you can always go to the Recreation room and throw grenades into the snooker table pockets. - An overview map of all floors is available at the map home page. - I hope that this map is balanced for use with all weapons. In the long corridors and halls the snipers will have an advantage. But in the cramped corridors of the office, the close range weapons will get the upper hand.

If there are known errors, describe them in this section. Also, to help users send on error reports: Describe how to::

Example:

>>>>>>>>>>>>>>> KNOWN ERRORS IN VERSION 1.1 <<<<<<<<<<<<<<<<<< - The balcony door is invisible when leaning out of the "desk document room" ( and the room straight across the corridor from it. >>>>>>>>>>>>>>>>>> REPORTING AN ERROR <<<<<<<<<<<<<<<<<<<<<<<< - To report errors in this map (something I would like a lot), make a screenshot by pressing F12 and send it to me with a description of the error, the address is on the map home page under the "contact" link.

If it is the first release of your mod / map, the version history will be short and contain something like "First version released". But still you should keep this section ( because users have no idea if this is the first version, just because it is named version 1.0. ).

Example:

>>>>>>>>>>>>>>>>>>> VERSION HISTORY <<<<<<<<<<<<<<<<<<<<<<<<<< Changes since version 1.0 - Calibrated the location of the boxes in the corridors for better gameplay. - "Repainted" the 2:ND floor corridor to give a better visual clue to the players of their location ( previously the corridor had the same texture as the corridor on the 3:rd floor ). - Calibrated the vis_leafgroup's to increase FPS and / or remove "vis_leafgroup brush popping". - Added an extra route into the "Large distiller hall" from the "Small distiller hall". Its an opening into the ventilation pipe connecting the two halls ( there are now 5 ways to approach that objective ). - Fixed that the poster "We are now in this war" in the red office was backwards ( mirrored ). - Fixed some weird"vis_leafgroup brush popping" when looking through the big loading doors into the loading bay area ( The roof was "popping" ). - Fixed some visible "vis_leafgroup brush popping" when standing at the ferrets edge, looking into the offices. Version 1.0 - First public release

People may want to praise you for a good work, tell you an error, say hi... or any other form of contact. And if they do; here is the section for getting in touch:

Example:

>>>>>>>>>>>>>>>>>>>>>>>> CONTACT <<<<<<<<<<<<<<<<<<<<<<<<<<<<< mail: rjukanproject@planetmedalofhonor.com ICQ : 7153676 IRC : irc://irc.quakenet.eu.org/FFisON

This section explains what permissions the users have to use your work. Don't be too restrictive here. I suggest something like this:

>>>>>>>>>>>>>>>>>>>>>>>> COPYRIGHT <<<<<<<<<<<<<<<<<<<<<<<<<<< - You MAY NOT use this level as a base to build additional levels without explicit permission of the author. - Also, this level MAY NOT be used for any kind of commercial product of any kind without written authorization from the author. - You MAY distribute this map as long as you include this file, intact, in the original archive. - You MAY download this map and run it on a public server as long as you send the author an e-mail about it. - You may use any resources from this map (scripts, shaders textures) as long as you give the author due credit.

Greet your readme file readers with a cheerful ending

Example:

>>>>>>>>>>>>>>>>>>>>>>>> GOOD-BYE <<<<<<<<<<<<<<<<<<<<<<<<<<<< Have fun, play fair. /Bjarne Grönnevik

So now we are done! There is no need for your readme to look exactly like mine, but it should contain the sections I outlined here. Good luck!

[ Download is an example readme file ]

[ Here is a tutorial on good file naming practice ]