Editing Style Guide


The following conventions are used by much of the present content of Running Reality. These are suggestions, which help achieve a uniform appearance across all Running Reality content provided by different users. Conventions attempt to achieve a balance between accuracy, management of information uncertainty, and rendered visual clarity.

Overview

This article covers the styles and conventions of making edits and complements the article on the mechanics of editing. Fully utilizing these styles and conventions will expedite review and approval of any factoid history data submissions.

Borders

Uncertainty in border edges should be represented by a smoothing of the edges. The degree of rounding may be made proportional to the uncertainty. For example, ancient cultures are often represented by nearly-round ovals across a general region.

When a river, stream, or bay is a likely edge to a border, trimming to that river/stream/bay is preferred.

Adjacent borders subject to uncertainty should be represented by a smooth gap between the borders, unless one border was known to be actively encroaching upon the other, such as during an invasion.

Overlapping borders should generally be reserved for times when physical overlapping of peoples was expected to be occurring, or when referenced maps show such overlaps themselves. In other circumstances, borders of two objects are derived from separate sources (and likely recorded on different dates), but lead to overlap at some other date within the timeline of both objects. This is expected and acceptable, however if one nation or cultural group can be determined with a small amount of extra research to be dominant to resolve the overlap, adding a new territory factoid to render this is preferred.

The division between when to use the Nation and CulturalGroup object types is ambiguous. ‘Nation’ may be used for a wide variety of entities believed to have a coherent state-like level of organization, even if not a nation-state in the modern sense.

Cultural Group object types may be used in a similarly flexible manner, representing both named groups of indigenous peoples, as well as stages of archeological periodization.

Nation borders are not intended to change during modern era conflicts with each step of each army, such as the Napoleonic Wars, WWI and WWII. Alternative occupied territory map objects serve this purpose in some circumstances.

Nation and Cultural Group borders should, when possible, not try to include every coastal detail and estuary on their edges, but instead should be drawn to near the coast they controlled. The reason for this is simply reduction in the memory/bandwidth demands of the Running Reality servers.

High resolution border details are often known in the early-modern era for regions such as Germany and the Low Countries. Detailing of such information is highly encouraged.

After creating a new object, it is recommended to check into the past and future for the lifecycle of the new object, to see if border matching in time is needed. The citation type ‘Match to Adjacent Object’ may be used to indicate when a new object was fit to preexisting objects, absent other temporal information.

Nature Objects

‘Bay’ objects are useful for defining coastlines with more meter-level fidelity than what is provided by the background map.

Defining coasts using ‘Bay’ objects works best when multiple levels of bays are used. For example ‘Baltimore Inner Harbor’, ‘Baltimore Outer Harbor’ and ‘Chesapeake Bay’ would all be separate entities. The reason for this is so that the entire largest object does not need to be updated across all time steps for every fine-scale change such as near a city center.

It is recommended to extend ‘Bay’ objects used for such purposes some distance out into the surrounding outer water body, so that colors match in the final map. Look at the background map tiles/pixels to get a sense how far out is appropriate. Take care to smooth corners and match coastlines near edges.

Polygon objects are currently limited to not contain holes. This makes definition of islands within bays difficult. Multiple surrounding bay objects may be used for this purpose.

Polygon objects of different types should not self-overlap. Objects of the same type (such as an inner harbor and outer harbor) may overlap by just a few tens of meters to prevent gapping.

‘TerrainAdjustment’ objects may be used as the opposite of ‘Bay’ objects, to create sharp land-side edges, in circumstances where the background map does not sufficiently make a region appear as solid ground, such as near river deltas and wetlands. You can set a custom color on a TerrainAdjustment to make it more precisely match the local background tile color.

Like all Running Reality objects, ‘Bay’ and ‘TerrainAdjustment’ objects can and are encouraged to change in time whenever appropriate.

Forests and Lakes containing many isolated sub-regions may be defined equally well either as one object with ‘regions’ or as multiple objects.

Stream and River objects may have their width defined, however this width applies for the full length of the object. If significant width change occurs and is relevant, multiple smaller objects may be used. Alternatively a Lake or Bay object may be used to define the tapering.

Bay or Lake objects are encouraged to be used to define complex river edges of historical importance that are poorly represented by a fixed-width meandering line.

If needed, one river may be represented by a combination of Bay/Lake, River, and Stream objects to create the best visual final result.

Users are encouraged to draw background objects such as parks or forests first, and route objects like streams and roads second.

Factoids defining the creation or removal of nature object types such as Forests and Lakes are optional, and should only be added if a clear change is known. Nature object types with no creation event factoid default to rendering indefinitely back in time.

Movements of Ships, Armies, People, and Things

Movements are a complex feature that brings life to the Running Reality map. The philosophy is "history playing out on a map" and not "a history map." The difference between these is that a dynamic world "model" shows movement whereas a map is static. However, representing movement is complex, especially when trying to properly represent that much historical movement information is inherently uncertain.

There are four types of movements that Running Reality understands, some of which are highly developed and some of which are still in development:

An alternative to an explicit movement is a series of single-point locations. Running Reality linearly interpolates the location of movable objects between known factoids. Use a series of single point locations if the historical record only documents when someone or something was in particular places. An example is a sculpture that is known to have been in multiple buildings and plazas, but the transit between them is unknown. In this way the factoids represent only what is explicitly known, the engine can interpolate the movement, and room is left for new knowledge to be added in between known points. Routes with waypoints should be used if it is wished to have a colored arrow render on-screen for the entire swath of motion, such as the full path of the advance or retreat of an army, or the full path of a ship's expedition.

If adding a new movable object, at a minimum, try to provide information on the location at beginning and end of lifecycle. A small number of waypoints may be used to represent motion.

If the time of transit between ports/locations not known, just place single-point location factoids, in order to allow the Running Reality interpolator engine to render a guess at the transit. Exception: if a large landmass exists between the known locations, it is desirable not to have the interpolator show the ship moving overland. Example: For a ship traveling from New York to San Francisco, when it’s known the ship probably would have gone through the Panama Canal. In this case it is acceptable to render a seabound path with a citation note that the start/end dates are a best guess.

Battles

A battle is an explicit object that can be added to the map and have its duration set. The duration will default to a single day. The location should be placed near the center of fighting and if it is a multi-day battle the location should be set near the center of fighting on the first day. The map of a battle can be enhanced if more detail about the armies, their units, and their maneuvers are known. Adding individual units with movement arrows along with field fortifications and landscape features can show a battle as richly as any historic battle map can.

IMPORTANT It is important to take the extra steps to link objects to one another. This does not affect the look of the map, but it is important to the underlying model of what happened. If two armies battled one another, explicitly linking them to the battle object as combatants makes it easier for users to know who the combatants were by looking in the sidebar of the battle or each army. Physical proximity to the battlefield does not automatically link combatants. Similarly, linking army units to the army makes their allegiance on the battlefield clear in the sidebar. It also associates the color and can move the unit with the army after the battle. The main army can also be linked to the nation and to commander(s) so links appear in the sidebar.


Colors should be set on the main army object. Main army colors should be set similar to the nation color, uniform color, or another neutral color. Units in the army that appear on the map only during a battle deployment should be linked to the main army. When linked, they automatically pick up the color and flag of the main unit -- and change color if the main unit's color is later updated. Alternatively, main units may be linked to their subunits to similar effect. Running Reality does not use NATO APP-6 color designations that indicate "friendly" versus "enemy" armies because it is a global, neutral map.


On the battlefield, use single-day movements and consider using the following standard patterns for consistency:

Armies and movable units following rivers or roads may be drawn to follow near but not on the road/river, such that both the movement arrow and underlying reason for that course are simultaneously visible.

Armies should be located partly behind front lines when known battles are about to occur, to leave visual room for future detailing of the positions of specific front line subunits.

Small forward motions may be used to indicate stance, even for cases where a unit did not significantly change position. For example, in an active battle, a back-row unit may be given a small forward arrow to indicate the direction in which they were firing/defending. This helps to indicate active participation in an action, versus units that are truly far behind the lines that were both motionless and inactive (or omnidirectional) in stance.

For visual clarity, try not to create too many overlaps of arrows, unless necessary.

Longer movement arrows covering lengthy time periods are useful for discoverability and for users learning the broad scope of what a unit was doing over time. Carefully consider if a long duration arrow is appropriate. For example: use if an army merely paused in multiple towns as it traveled across a countryside, but generally kept active and moving as part of a long campaign.

If historically appropriate, try to match the duration of movement arrows of opposing units, such that maps break down in time into sequential coherent and easier to understand campaigns of action.

The exact start/end location/time of an army before/after a historical battle is often difficult information to obtain. After entering known information, check if the years/months ahead and behind the events just modeled, are at least reasonable given such uncertainty. Additional guesses for locations as well as start/end factoids may then be used to prevent obvious inconsistencies, such as a unit persisting behind enemy lines.

NOTE There is an older style of battles that you will see across the map. This older style had the battle as an event associated with one of the combatants and then had the other combatant(s) linked to the first combatant. This approach had many weaknesses, especially when the army names or exact positions were unknown or when the battle extended over multiple days. New battles should not use the old system and battles represented by the old system are being slowly replaced with the new style approach to the data.

Start and End Dates

Towns should be founded on the first day they physically exist, not on the later date of formal incorporation. Incorporation may be listed as an event afterwards to make this distinction.

Building objects should start at the moment of first physical existence of any part of the structure, i.e., at groundbreaking. Completion/opening dates are appropriate if they are the only dates known.

Towns and buildings typically continue to physically exist even as ruins. Therefore it is preferred to mark them with appropriate event flags that change how they render, not erase them from the map. In rare cases complete removal is appropriate.

Similarly, for ships, railroads, roads, etc., mark the first/last dates of physical existence.

The date on which ancient cities gradually convert from occupied to abandoned is often not known. However, eventually it often becomes appropriate for a city to be rendered instead as a ‘ruins’ icon. In this circumstance it is acceptable to place an ‘abandoned’ event for that city using the ‘Educated Guess’ citation type.

The start dates of most indigenous peoples is generally very uncertain. Many of the earliest groups mapped could reasonably be claimed to date back to 100,000 years ago, or even one million years ago. Some criteria for when to chose to begin rendering the object on the map can include:

Dates prior to 3000BC are acceptable and encouraged. Dates earlier than approximately 20,000 BC however should generally not be used.

Mapped indigenous groups tend to end in two ways: they are divided up into a larger number of smaller named groups, reflective of more information existing on a more recent time. Or else, they are overprinted by a nation-state. Typically the indigenous people continue within the nation-state for a long time after, often to present day, but only in a few cases in Running Reality is this later history rendered geographically. The following are useful conventions for how to mark start/end events for such groups:

Running Reality uses the following default conventions in its rendering engine for when start/end event information is not provided:

Cities

All human settlements are regarded as ‘City’ object types in Running Reality regardless of population.

To visually distinguish between large and small settlements, Running Reality uses population factoids to render the diameter of an on-screen oval. Therefore, especially in the ancient era, to mark a settlement as small, a population factoid, even if an educated guess, may be useful.

The number of small modern towns shown in Running Reality is limited, but literally all named towns, large and small, are highly encouraged to be added and perhaps even given detailing by users.

There are three basic approaches to detail a city/town:

To begin detailing a city, it is often helpful to first look up the oldest known structures in that city, such as ancient temples. Adding early buildings first will help to frame which areas of a city were constructed at what times.

When a building appears, it is plausible that the earliest roads to that location may have also appeared. If better information is not available, the factoid citation type “Match to Adjacent Object in Time”, may be used to indicate the plausible appearance of roads because of the appearance of buildings nearby. All such citations assume they may eventually be corrected by better maps.

‘Road’ objects are used to represent all similar human pathways, from dirt tracks on up to superhighways. ‘Width factoids’ may be specified, to visually differentiate narrow medieval alleyways, dirt roads, large avenues, and broad highways. Airport runways may also be specified in this manner.

City walls, when appropriate, are highly effective in visually representing the populated extent of cities in the ancient era, even when detailed road locations are not known. Therefore, adding city walls first, can be valuable.

City walls often exist to the present day, even as ruins, and even if only in small remnant segments. Therefore, most city walls are created with the assumption they ‘exist up to the present day’, and changes in the route factoid are often best for when major sections are torn down.

Canal, Lake, or Bay objects, may all be used as appropriate, to delineate moats and waterways between early-modern fortifications and city wall bastions.

Citations

Check the current reference list to see if the source you are using is already entered.

For journal articles, the first word in the name should typically be the surname of the first author.

Use ‘et al.’ for more than three authors.

For maps, the first word of the citation name field is encouraged to be the year of the map, so that maps can easily be perused in the reference list by date.

Wikipedia (and similar sites) can be useful as a reference without further detailed attribution for the following:

Wikipedia is less preferred for geospatial information, in which case specific named maps are strongly preferred if known.

Often multiple citations are involved in one factoid, as factoids include both temporal and spatial information. If one citation is more unique, or more dominant, it should be the item entered. For example, if a specific named historical city map is being used for reference, but an educated guess is also used to build a road from that map at an earlier date than the map itself, use the citation for the map, not the ‘Educated Guess’ citation type.

If a single citation is truly insufficient, use the ‘Note’ tab to attach a note to a new factoid. Notes should be reasonably brief, as they must be downloaded along with all factoid datasets.

Names

When possible, prefer the use of named objects over unnamed ‘anonymous’ objects. The primary exceptions to this guidance include nature objects such as forests, or pre-modern city roads. An object is automatically made ‘anonymous’ simply by creating a new object with an empty name field.

Matching to names used in Wikipedia articles helps allow automatic linking of Wikipedia entries to objects in maps. Alternatively, such linking may be achieved by use of the ‘catalogname’ special factoid type.

Capitalization of all primary words within proper names, is the standard for Running Reality objects.

Modern names are preferred as object names. Historical names are best set as ‘altnames’, as well as ‘displaynames’ that vary the object label in time.

Commas are acceptable and have a unique purpose. Name text after commas is not rendered within on-map labels. This is useful for creating unique object names in the system but not overwhelming the map with information, such as town names that repeat across several U.S. States.

Dashes are acceptable.

Parentheses are not allowed.

Leading spaces are not allowed.

Naming conventions for military objects are complex. The following conventions are useful:

Colors

Nations, Cultural Groups, Provinces, and Armies, are assigned colors randomly but may be overridden with explicit colors. The Running Reality team is ultimately responsible for map coloration choices but welcomes color suggestions for new objects being submitted.

Scan all past/future adjacent boundaries for color conflicts.

For army unit colors, match to other army units of the same nation.

If no such objects exist for that nation yet, match close to that nation’s color if possible without generating visual conflict.

For visual clarity, consider red/blue pairing for ancient battles where few other conflicts with other nations/groups will occur. For the modern era, red and blue are in high demand, and not all pairings may take advantage of their high visual contrast.

Use subtle shade variations for units of the same nation acting near one another.

Provinces of a Nation should use subtle shade variations of the host nation color.

Distant overseas colonies of a Nation are preferred to be recorded as separate objects, but should use a color similar to the host country if possible.

Feedback


If you can not find an answer here, please feel free to ask us for help. Send us an email if you would like us to get back to you with a response:

Send the Running Reality team an email: