A map definition is very much like a .arena file from Quake 3. It defines the name of the map, what gameplay modes it supports, and how large it is (in bytes) at each quality mode.

mapDef game/alphalabs1 {
    "name"     "Alpha Labs Sector 1"
    "devname"  "05-Alpha 1"
    "singleplayer"    "1"
    "size0"    "208322592"
    "size1"    "208322592"
    "size2"    "325950691"
    "size3"    "470025492"
}

mapDef game/mp/d3dm5 {
    "name"       "Lights Out"
    "Deathmatch" "1"
    "Team DM"    "1"
    "Last Man"   "1"
    "Tourney"    "1"
    "size0"      "93855710"
    "size1"      "93855710"
    "size2"      "156267217"
    "size3"      "237413960"
}

The fields in this decl should be pretty easy to figure out, "devname" is the internal name that we refered to the map by. It was mostly used by the 'takeViewNotes2' command, which probably doesn't work any more (it was used internally to help with finding bugs).

A map can still be loaded for a specific game type, even if the mapDef doesn't have the game type listed, by specifying the map in the console. The game type is only used for listing maps in the create server and vote menus.

The only hard part about creating a mapDef is specifying the sizes. The cvar "com_updateLoadSize" helps with this a lot. When that cvar is set to 1, the game will automatically update the size info in the map def after the map has loaded (it must not be set read only). After making a build, we would run a batch file that launched the game with com_updateLoadSize set, load a map, exit the game, repeat. We would do this for all 4 quality modes (though size0 and size1 tend to always be the same).

Here's a snippet from the batch file:

doom3.exe +com_updateLoadSize 1 +map game\admin.map +quit
doom3.exe +com_updateLoadSize 1 +map game\alphalabs1.map +quit
doom3.exe +com_updateLoadSize 1 +si_map game\mp\d3dm1.map +si_pure 0 +spawnserver +quit
doom3.exe +com_updateLoadSize 1 +si_map game\mp\d3dm2.map +si_pure 0 +spawnserver +quit

The mapdef does not have to be in a def file. It can be in any file you want, even a material file! I would strongly suggest, though, creating <mymap>.def in the defs folder with a mapdef in it (along with any entityDefs or custom models you may be using).