Hint brushes
(Note there is three pages to this tutorial but don't jump around the first time that you read them)

This is one of the hardest tutorials sets that I have ever written.
To start out, I would like to thank SmallPileofGibs. Without him I would still be trying to figure out hint brushes.
If you haven't read SmallPileofGibs' (SPoG) Q3map explanation go read it now. I suggest saving it to print out and study. I know I did. Link to SPoG's technical note.
If you have read the note, but you have found it difficult to follow, the aim of this tutorial is to help you understand it.

To work out how to use hints, you need to understand the concept of visibility (Vis stage) in a compiled map (the .bsp). 

In a compiled map, all the space where a player could travel is made up of leaf-nodes (a node and a leaf are the same thing).
To grasp what these leaf-nodes are think of them as convex (not concave) invisible brushes that started as a big block that filled the interior space of the map, and this block was CSG subtracted by all structural brushes and hint brushes. If you have ever tried a CSG cut with many brushes you'll know what a mess it can make.
Each of the leaf-nodes (the brush like spaces) touches a few other to many other leaf-nodes. Where one leaf-node touches another, it makes a portal. Think of a portal as a window. Players must pass through a portal to get from one leaf-node to another. From the leaf-node where the player is standing it is possible to see a set of other leaf-nodes. This set of leaf-nodes is potentially visible to the player. This is called the potentially visible set (PVS) for that leaf-node. 
To view (PVS) in the game with cheats on type \r_lockpvs 1 in the console. The only purpose of Q3map -vis stage is to calculate the PVS for each leaf-node. Q3map uses the portals for each leaf-node to calculate the PVS.

Leaf-nodes don't always form where you want them to and can be part of the PVS even when structural brushes apparently intervene.
This is why the Quake3 engine could be drawing areas that you can't see because the Quake3 engine thinks you can.
This is the reason for hint brushes. But wait - there is more to explain before we get into some examples of hint placement.

Quake3 draws all the surfaces touching all the leaf-nodes in the PVS for the leaf-node where the player is standing. Hint brushes do not split the faces of brushes like they did in Quake2. This is why a single brush or a mesh will be drawn by Quake3engine if it is on both sides of a portal, to avoid this from happening build your map so the brushes and meshes are split along the portal plane. This will help keep r_speeds lower but will also increase them when a player's PVS can see both sides of the portal plane because there will be more surfaces to render.

How does q3map decide where to put each leaf-node? If you think of a compiled map as a hollow space carved out of a large block, again the carving is only from structural brushes and hint brushes, not from detail brushes, meshes (curves), and brushes with a non-solid property (like those with trans textures).  

The first cuts are based on the blocks that are cubes 1024*1024*1024. To view these blocks go to the view > show > show blocks option in Q3Radiant. Next it picks the first chunk and checks if the space in that chunk is convex. If not, it then picks a brush face in that space and splits the space in two along the plane of the brush face. If the space was concave and was split in two to make two new leaf-nodes, then q3map has to check the two new leaf-nodes created to see if they're convex, and split them again if they aren't and so on and so on until they are all convex. Next the process moves on to the next chunk and starts again. Eventually the whole map is split into convex spaces called leaf-nodes.
There is nothing controlling the size or shape of the leaf-nodes in the vis stage described above. This is what hint brushes are for. Hint brushes are simply brushes  with the common/hint shader on all faces. Q3map treats common/hint brushes exactly the same way as structural brushes when creating the leave-nodes, because common/hint shader contains surfaceparm structural. Think of them as invisible structural brushes. Leaf-nodes are always made along the faces of structural brushes. Thus a hint brush is very helpful in controlling the portals and your PVS.

Did you follow all of that? If not, read it again and again until you do. 

Page two of Hint brushes covers some examples of hint placement in a simple map. Note that there are many ways to place them. Practice and testing is the best way to understand hint brush placement. Although these pics and notes may help you, they are in no way the only way to use hints. The page has many pics so give it time to load.

Note the hints in id's example maps don't make sense to me. If they do to anybody reading this, please write me and tell me why they put them were they did. My email is at the bottom of every page.

Useful short cuts and tips for hint brush placement.

ctrl+h to toggle hints on and off
ctrl+d to toggle detail brushes of and on
ctrl+p to toggle meshes off and on
ctrl+m to make a selected brush detail
shift+ctrl+s to make a selected brush structural 
shift+left mouse click to select multiple brushes

Grab a front end compiler like Q3Map Explorer  or
Q3Build  this will make it easy to load the map with different options, also compile options.

Smallpileofgibs handy hint_maps zip examples of hint brush placements.

If you don't want to use a front end compiler use a command like this for the vis stage    C:\Program Files\Quake III Arena\Tools\q3map.exe" -vis -saveprt -threads 1 "C:\Program Files\Quake III Arena\baseq3\maps\fpshint1b.bsp" >>C:\WINDOWS\TEMP\fpshint1b.cvis
Change the paths to what- ever folders you use and map name.
Check this link   to John 'Anwulf' Hutton's site if you still need help on this.

Load your map after a full vis also use the save .prt option compile with the cheats on by typing in the console \devmap yourmapname

To view (PVS) in the game, first load the map with cheats on (\devmap mapname), next in the console type \r_lockpvs 1 
With the pvs locked the game engine will only draw the part of the map that it can see (PVS) from were you typed in the command. The same command but with a 0 (zero) unlocks the (PVS).

To view the brush cuts and also what the engine sees in the console with the map already loaded with cheats on type \r_showtris 1 same but with a 0 to turn off.

Load up you map in Q3Radiant now go to plugins and then portal viewer then load .prt file you can view the portals in both the 2d and 3d windows. This won't work if you didn't compile the map with a full vis and the option save .prt