The Unofficial Official VDU Style Guide

(October 11, 2017)

"I swear r_speeds are still relevant—"

Aside from the site just...not being a thing anymore, when this was written, we were working on an increasingly bizarre mixture of custom HTML-like syntax and Markdown. Now, we're basically just using raw HTML, which is far less confusing. Keep this in mind if you dare to contribute this time around. (Also, in case you were wondering, only two people ever contributed site content other than me and Jax on one or two occasions.)

Writing a guide isn't easy. Even smaller guides require a working understanding of the topic at hand, perhaps some testing, and most definitely screenshots. A large guide might take me two days of on-and-off work, and that's with me rushing near the end.

That's why we're reaching out to you, the modding community. You know things I don't and the people around you don't. We have gaps in our collective knowledge big enough to fall into, and sites disappearing for lack of funding or interest doesn't help. The Valve Developer Union is an archive just as much as it is a site for tutorials.

The issue is the amount of organization a site like this takes. Effective communication is sink-or-swim for a tutorial, and some of us aren't the best of writers. Rather than cast you into the role of guide writer (should you choose to accept it, of course) without any guidelines on the how or what or where, I've put together this style guide for how I structure my guides and how, ideally, you would too. If you don't feel like reading, though, here's the summary.

Guides in a nutshell

1. A guide should answer a question. Think of something you might ask yourself while you're working on a mod. Questions like "How do I get good looking fog?", "How do I rig a playermodel for Garry's Mod?", or "What is a 3D skybox?" are all ripe pickings for guides.
2. Structure it well. An intro paragraph should introduce your topic. A closer paragraph should sum it up. The in-between should explore the topic, whether that be an entity, an effect, or a concept. As much as you're tempted to do so, never write in the first person ("I'll then use the vertex tool...").
3. Don't assume the people reading know anything about modding. Your explanations should be readable to someone who has never touched a level editor, or maybe even a video game. Explain the terms you use; even if I'm coming from another engine, Source-specific concepts like Actbusy routines or materials might be foreign to me. If you're telling them to put down a point entity, explain what that entity does.
4. Write clear and concise paragraphs. A bit of length for a lot of clarity goes a long way, but don't be so long-winded that you ramble. Make it as long as it needs to be and no longer. Sentences aren't paragraphs, and sentences need a subject and a verb. Lists are also not paragraphs. Images should stand on their own or be supported by the paragraphs immediate before or after it.
5. We can always edit it. These are guidelines, not laws. Don't be intimidated if you're a talented modeler with knowledge of something few others do, but aren't a very good writer or communicator. That's why we're here. We can help you chop it down. Just zip it all up and send it to us.

Choosing a topic

Treat every guide like you're explaining a concept to someone. We've all gone into a project and realized we don't know how to pull off a specific aspect of that project. If you've asked a question, someone else has asked that question too. Below are some sample questions that would be perfectly ideal as guide topics:

• How do I make custom sprites and add them to my GoldSrc map?
• Why do my Half-Life NPCs have yellow "pollen" sprites surrounding them?
• Why is cs_office such an effective Counter-Strike level?
• How do I add phong highlights to my model?
• What is lights.rad and how do I make use of it?

In short, technical guides should be very specific, but bigger and more intricate guides, like level dissections, are more open to discussion.

Our focus is generally on the GoldSrc and Source engines and their respective games, though branching out to Quake and other Quake-based engines is definitely up for discussion. More general level design topics without something to tie it to a Valve engine ("How do various colors of light affect the player?"), topics that don't relate to Valve engines at all ("How do I add a skeleton to my Blender model?"), and opinions ("Why is J.A.C.K. such a good level editor?") aren't good topics, so don't come to us with those.

Writing the guide

The technology behind the guide is simple: I write mine in Notepad++ and format everything in Markdown (aside from . All guides on the site are written in Markdown; it's easy to write, it's easy to read even if it's not parsed, and it's what everyone else uses for lightweight formatting, including Discord. There's not a whole lot to remember with Markdown.

Tone and terminology

With a guide, remember to stay objective and as concise as you can. This is the part that'll invariably trip people up. Writing classes in the United States are sorely lacking, and as a result, a rather large portion of the English speaking world doesn't learn how to communicate properly in the written word whatsoever, especially in anything longer than a sentence or two.

In general, you'll want to write like a historian, not like a player. Don't talk about your favorite weapon or your favorite class. We're here to focus on why things work, not what those things are. Talking about commonly abused sniper points in a map is okay, but telling us where you like to camp in a map isn't. If you're talking about why de_tides is such a great map, establish its status in the greater Counter-Strike community, not how much you like the look of it.

When you're explaining technical topics, define your subject. "Cubemap" only makes sense if you know what it is. As soon as you define that term ("a set of six images that can be mapped into a cube shape and used as a faster, fake reflection"), everyone knows what you're talking about. If you can, find someone who doesn't do the tech stuff and see if they understand your definitions and what you're on about. If they do, you're probably on the right track.

Don't write in first-person singular ("I'll texture this face with nodraw") and try not to write in first-person plural ("We recommend you use"). The focus should remain on the content and the end user, not you. No one cares how you like to not merge corner brushes, or how you like low skybox ceilings. If you have to write it in first-person singular, the vast majority of the time, it's irrelevant to the guide. If you're giving directions, give directions. Don't call it a recommendation, and don't coat it with empty words like "you'll want to" or "try to".

Jokes also do not belong in a guide. If you get the urge to write this:

Remember the first time you got your dirty mitts on the Tau Cannon from Half-Life 1? It was awesome. It two-shotted nearly everything that wasn't an alien grunt, and if you charged it up properly, could take down those annoying helicopters! Shame, the poor bastard only had like, what, 2 or 3 ammunition boxes throughout the entire game. (This is sarcasm.)

Don't.

Structure

When it comes to a guide, your intro paragraph(s) should introduce the topic at hand. I'll be using a few examples from one of my most recent guides as of writing this, the one on cubemaps:

If the Source engine were to calculate reflections in real time for every piece of metal and glass in a scene, it would make all but the most competent computers crack under the pressure of rendering it. Instead, Valve implemented a tradeoff that looks the part but is much less expensive to run: cubemaps.

A cubemap is a set of six images, one for each face of a cube, that can be rendered in place of the scene itself in the reflection of shiny materials. Cubemaps are completely static. Whatever props, lights, and scenery around are baked into the cubemap. Players, changes in scenery, decals, and anything not present at time of rendering will not appear in a cubemap when the map is played.

Notice how I begin with the problem cubemaps are designed to fix: reflections are expensive to render. Thus, you make fake ones. Remember that engine features, especially more esoteric ones, are usually designed to solve problems. The BSP map format came about as a way to make storing map data easier and quicker to root through. Areaportals help render fewer things on the screen at once. Explain why it's there.

Don't write more than you need to. Thoroughness is a virtue until it trips people up. In that same guide, I omitted mention of the "cubemaps not rendering" glitch affecting only Source 2013 games (Half-Life 2 and Deathmatch, Portal, and so on) because it would've convoluted matters. "What is Source 2013? Is my game Source 2013? Am I missing something?" people would ask. It's really easy to trip up an audience with jargon like "Source 2013 games", and you're not here to show off your knowledge of the engine.

Finally, make sure you have a conclusion. It'll help you structure the guide, and it's really just a nice summation of the above. It's closure. You can put additional advice in here or just reiterate something important. Again, from the cubemaps guide:

Cubemaps are an important part of getting the look of your map right. Never release a map without building them, arduous as they may be.

Getting screenshots

I use Snipping Tool for all of the non-game screenshots on the site. It's pretty helpful, especially the "window snip" mode that takes a screenshot of the entire window, ideal for tools and other smaller and more variable window sizes. It comes with Windows, too. It doesn't much matter what you use so long as it isn't an actual camera and it can do PNG. For game screenshots, I take a TGA or a BMP in-game and save it to JPG in IrfanView. I don't really need to, but I like the extra control I have if needed.

Err on the side of getting more screenshots than you need. Get screenshots of editor dialogs, effects in-game, tools you use to achieve certain effects, and so on. Screenshots provide context and visual interest to a guide, which is important. Obviously, you want it to make sense with your text. If you can't contribute screenshots, or if they're subpar, don't worry. If you do, though, here's a few guidelines:

• If it's of a dialog box in the editor or something in the UI: Don't scale it up or down. Try to get the image as close to the size of the real thing as you can, and no more. Remember, Snipping Tool's window snip mode is invaluable for stuff like this. If you can crop it in an image editor, even better. Save it as PNG.
• If it's of something in-game or Hammer's in-editor preview: You can use screenshot (for Source games), snapshot (for GoldSrc games), or the venerable jpeg. Fish it out of your files and save it as a JPG. If it's already a JPG, don't re-encode it, shrink it, or crop it. All of our in-game screenshots are 1920x1080 JPGs.
• If it's something normally unseen, technical, or raw source material, like specular maps or bumpmaps: Don't scale or crop it. Export as PNG.

Try to hide your HUD or any viewmodels unless they're needed for context. cl_drawhud and r_drawviewmodel are what you'll want to disable. notarget or ai_disable is also worth mentioning, as it'll make enemies ignore you or disable their AI outright.

Remember that screenshots are shrunken by a bunch of things, mostly window size. Try to get as close as you can to the subject. We have had instances where we've needed to replace screenshots because they looked alright at full size, but are indecipherable when shrunken. You can expect a 1080p in-game screenshot to be shrunken down to 800x450 on the site.

Submitting the guide

Head to our Discord if you're not there already. Don't be shy, we don't bite. You'll wanna ask for an administrator, probably pac (me!) but maybe Jax if I'm not available.

Submit your guide as plain text and zip it up if you have any attachments. If you don't know how to save a text file, you're probably not gonna be a very good guide writer. I'm sorry.

From there, we'll end up mercilessly editing and cutting up your guide, introducing new screenshots if needed and testing everything. We're here to get the information up, not to highlight the people who wrote it down. Don't be offended if the guide goes up and looks nothing like what you sent.

On the flip side, if you're the type to introduce your guide as garbage, don't worry about getting it perfect before you send it. Just submitting something in the first place is greatly appreciated. If you're really into the idea of contributing but you're not very good at it, we'll work with you. Writing, especially technical writing, is a skill, and you can develop it.

We eagerly await what you come up with. And by we, I mean me, because it means I don't have to write everything for once.

-pac