User:Blixibon/sandbox/Help:Differences in games
Note:Any game, mod, or other specific software mentioned here is used for the sake of example. There is not necessarily a precedent for these programs receiving undue documentation.The VDC is a wiki for anyone working with Valve's tools, which generally means people working within the 
Source, 
GoldSrc, and 
Source 2 engines. However, technical differences between games and branches make these engines difficult to define, and even more difficult to document cleanly. Most of the VDC's users have different needs and expectations based on the game or engine branch they're working with. These differences manifest not only in the user base, but in the documentation as well, and it's important to keep them in sync. This article attempts to clear up the best ways to convey information about differences between games, engine branches, and mods for a single subject.
Articles should cater to their target audience
Generally, an article should cater to its target audience as much as possible. For example, the target audience for an entity which only exists in 
Portal 2 would be Portal 2 modders. The entity isn't relevant to anyone who's not working in Portal 2, so it can easily stay concise to its readers. On the flipside, the target audience for an entity used in several Source engine games would be much larger. It could include Portal 2 modders as well as modders for any other game, and the page needs to be relevant between them all.
For most articles, this is fairly straightforward, but it gets complicated when the subject is different in one of the games it applies to, and those differences need their own documentation. For example, if a part of a base Source engine feature is broken in Portal 2, you would ideally want to document that. However, documenting differences comes with a caveat: When a part of an article is dedicated to one game or engine branch, that part becomes irrelevant to anyone who is not working within it.
For most subjects, these differences are inevitable, and it's often better to document differences than to not. To help document those differences cleanly, the VDC uses a set of inline notice templates ({{In}}, {{Also}}, {{Only}}, {{Since}}, {{Removed}}, and {{Not}}) which indicate a feature has different availability between different games or branches of Source. These are normally appended at the ends of list items, such as keyvalues or material parameters.
Unfortunately, being able to clearly see these differences doesn't fix everything. As the number of differences documented in an article rises, the article becomes more about the differences than about the subject those differences relate to. For example, several disjointed notes covering changes in Portal 2 within an article which covers several other games will be irrelevant to those other games, and it may become more difficult for viewers to find the information they're looking for. In order to keep an article in sync with a broader target audience, these differences should be either as small or as clearly separated as possible.
Proportions of audiences
Practically speaking, a target audience split between multiple games is unlikely to have an equal numbers of users for each game. For example, the env_gunfire entity exists in all Source games, but it's mostly useful for Half-Life 2 due to the nature of its gameplay and setting. There may also be differences in an entity's use between singleplayer games and multiplayer games.
Since the target audience of an article needs to line up with the documentation of differences on the article, it is important to consider the number of people who can benefit from information compared to those who could be distracted by it. However, this can be a difficult issue to approach because editors who work within only one or a few specific games may not have enough insight to judge how relevant they are to other games.
In most cases, making assumptions about the target audience isn't necessary, but generally, when documenting differences, try to be humble. Assume any differences you're documenting are only relevant to a small minority of people, especially if it's a smaller or third party/community project.
Examples
A regular article about something in the base Source engine. It contains no game-specific information and thus caters to anyone working within Source.
The same article, but with documentation for
Left 4 Dead and Portal 2-specific differences. These differences are small and don't distract from the rest of the article much.
The above images show examples of articles where differences between games either don't exist or are negligible.
The following image shows where problems begin to arise:
This article has Left 4 Dead's differences taking up a lot of the article's space in disjointed places. This is bad because it distracts readers who are not working with Left 4 Dead, essentially canceling out random portions of the article.
In this situation, you should consider splitting those differences into their own clearly marked section or creating an independent article dedicated to this feature's behavior in Left 4 Dead. Collapsible boxes or tabs to quickly switch between articles should also be considered.
An independent Left 4 Dead section in an article about all Source engine games.
An independent Left 4 Dead article paired with a general article for other Source engine games.
Use common sense to determine how differences should be separated. Creating a completely separate article may lead to some of the general information being duplicated, which isn't desirable, but may be a better alternative to a section in the main article.
Subsets of a target audience
A target audience for one article can usually be considered a subset of another, larger target audience. For example, people working with Source are a subset of people working with Valve's tools. People working with 
Alien Swarm are a subset of people working with Source. People working with 
Alien Swarm: Reactive Drop are a subset of people working with Alien Swarm.
The diagram below illustrates these relationships:
This becomes more important when documenting items at the lower levels of this hierarchy (e.g. mods) on subjects which relate to the higher levels (e.g. other games). For example, if you mention a difference in a mod on an article about all games in Source:
- (representation of a regular base Source article with small Alien Swarm: Reactive Drop-specific circle)
...it may actually apply to a very small target audience, as people working with a mod are a subset of people working within their respective game, and therefore the mod has a fraction of the relevance for the game the mod is a part of.
On the other hand, if you mention a difference in a mod on an article about the game the mod is for:
- (representation of a regular base Source article with the Reactive Drop circle replaced with an Alien Swarm circle with a very tiny Reactive Drop dot inside of it)
The target audience for the mod may be much larger, as the target audience for the mod is a direct subset of the game it's documenting.