Readme file content standard

[Bjarne BZR]

So, I've completed a tutorial on making ( a good ) readme file.
Check it out to see if you agree with me here ... I need feedback on this.

[ZeroSkaten]

sweet

[PsychoE]

Darn - i just finished one and now i gotta do it over again. We need some sort of standardization, so I say "GO FOR IT!!"

[panTera]

(this is how we used to do it for quake2:)

29.06.99

Map Information
Title: Imminent Demise
File Name: demise.bsp
Author: Chris "Kanaeda" Voss, Ritual Entertainment
URL: ...
Email: ...

Description:
Quake 2 DM map designed for 1-on-1 duels, 2-on-2 team play, and 3-6 player FFA. I recomend weaponstay on for 5 or more players.

Other Maps:
Burn Cycle (burn.bsp)

Play Information
Game: Quake 2
Single Player: Yer joking...right?
Co-op: Nope
Deathmatch: Now you're catching on (6 spawn points)
New Textures: No
New Sounds: No

Construction Information
Base: Out of nothing, I made something. ,-)
Build Time: Too long, and then some.
Compile Time: Does it really matter to you?
Editor used: QERadiant
Compile tools: QBSP3, QVIS3, ArghRAD2.0
Known Bugs: None so far.

Thanks to the Following:
...
id Software for starting the FPS revolution.
Robert Duffy for QERadiant - You da man!
Tim Wright (Argh!) for the irreplacable arghRAD 2.0
(phong shading ROXXX!)
Shane 'Fishman' Sherman for starting RUST, the best site around for
all your editing info. needs, as well as some killer forums.
Mike Malakhov for writing the awesome CRBot, my personal choice for playtesting without other people.

Copyright / Permissions
You MAY NOT use this level as a base to build additional levels without
explicit permission of the author, namely me. You MAY NOT de-compile and convert this map in ANY way, shape, or form. Don't ask me, cuz you CANNOT do it. Also, this level MAY NOT be used for any kind of commercial product or CD compilation of any kind without explicit WRITTEN authorization from me first.
You MAY distribute this BSP in any electronic format (BBS, Internet, etc.) as long as you include this file, intact, in the original archive.
You also MAY enjoy this map if you feel so inclined. You MAY download this map and run it on a public server as long as you let me know so I can come play, too. Ya never know, it just might happen. -o)

[mohaa_rox]

I write my readme file something like this:

Title version # by mohaa_rox

Brief introduction:
.............

Features:
1)
2)

Bugs:
1)

What's new in version #:
1)added xxx

How to install:
Just place the pk3 file into the mohaa\main folder.

How to uninstall:
Just remove the pk3 file from the mohaa\main folder.

If any comments/suggestions/bug reports pls email them to xxx@xxx.com
Thanks.

That's how I write. Simple tough.

[$ilver@cer]

Just make something original, but keep it simple!

What we did with QuakeII, like 'Pan' says is by far the best way! People want the facts plain en simple. People want to play the map, and sometimes read the file, and if you make a long story, they will stop ready if it's boring... Just make a text-file and add it to your .pk3 and zip-file. If you want something more interesting, go ahead, it's your map.

Cheers,
$ilver@cer

[mohaa_rox]

Yes, plain and simple, reduces the pain of reading.

PanTera and Bjarne, I think you're readmes are a bit too long, just a suggestion, keep important stuff there, no need for long-windedness.

I think MapRaider way of promoting maps, e.g. Title, Version No., Max no. of players, Description, Gametype are very useful. Go there and see how they do it. Should be included in your readmes.

Cheers!

[Bjarne BZR]

panTera: The Other maps & Copyright are good sections to use. I think I'll add them.

mohaa_rox: Maby I'll convert the Install section to a Install/Uninistall section.

$ilver@cer: U R totally right, if you find a section is without function for your mod, there is no reason to include it jut because it "must be there"... But I feel that too much info is better than too little, lets face it: We never read readme files... Not unless we really NEED to find some info. And way to often I've found a readme file contaning rubbish...

[mohaa_rox]

Yeah, you're right. I think MapRaider has the best readme format.

[Bjarne BZR]

Rox? Did you just agree with your own post?

[Bjarne BZR]

I updated the readme tutorial. I think the "keep it simple" comments are just lazy people talking...
- Its very easy to find the information you are looking for in a well-structured file with lots of information in it.
- Its very hard to find the informaition you are looking for in a file that does not contain the information you are looking for.

Right?

But for the lazy dudes; there is a template you can download in the readme tutorial ( just change or remove the sections you like / dont like ).

[Surgeon]

I gotta say i've used the syle of readme.txt that Pantera has shown : not because I'm lazy but because I realise that no one wants to wade through pages of txt. They just want the barebones info....just my 2 cents

[Bjarne BZR]

I agree with Surgeon ( and obviously also whith panTera ), and following the tutorial, that is how most readmes will look... The example readme contains all the stuff I could think of, and because of this gets rather big ( actual history and anekdotes and all of that ).
But as I hope I point out in the tutorial: Not all sections are needed for all mods ( mostly very few ).

So my example file is large, but most readmes following the standard will become a lot smaller...

What i want to get into focus here is:

Is it a good format?
Is it acceptable as a loose standard?
Is the readme file such a complex thing that it can't be standardized at all?
Is there any point at all to even try to set a standard?

[m4rine]

i think Bjarne tutorial is really good. there is a contents so if people dont want to read it all they can skip to the important bit

8) i'm going to use the tutorial when i release my map