STEP:Mod-Build Guide Framework

Game Guide Framework

Understanding Step's framework for creating and maintaining Game Guides

by: Step Modifications | Forum Topic

WIP

This reference guide is a WIP, so please add information where necessary if you think it would be helpful for others learning how to use the framework.

For those interested in using our framework, please also refer to some basic guidelines (and rules) for curating content on the Step wiki:

This wiki makes use of Semantic Mediawiki (SMW) to facilitate the functionality needed for our Game Guide framework. SMW is a fairly major extension that will not be covered in detail here. Just know that the entire framework would not be possible without it.

Step has many guide types, but most notable are guides for supported games. This documentation applies to these guides specifically. For assistance with any step(s) in this process, please contact site Administrators or Step Admin.

Step has built out an improved guide-creation infrastructure that confers the following important benefits to guide curators:

Assists ALL guide curators by 'seeding' available mod pages and guide instructions for use in other guides for the same supported game
Exposes guides on the game "home" pages to improve visibility and facilitate sharing
Standardizes and simplifies guide/changelog creation and maintenance
Standardizes all guides to a common look/feel with capacity to 'brand' unofficial guides
Reusable mod pages with guide-version-specific installation instructions

NOTE

It is essential to become familiar with the "Step Portal", "Game Home" pages, and "Game Portal" pages, where a brief rendition of these instructions also exists.

Step 1: Create/Update Mod Pages

The Step wiki parses all game-specific pages by namespace (aka, "GameSpace"), and mod pages are no exception. This how multiple games are supported by the infrastructure. Mod pages on the wiki serve several key purposes:

Provide guide-version-specific mod installation/setup instructions
Provide links to:
1. Mod source
2. Step forum discussion for the mod
3. Step ModGroup list
Provide metadata 'flags' used as visual indicators and query attributes
Allow title/instruction/attribute 'tansclusion' into ModList and guide tables
Make mods available to mod list queries/exports
Can be reused across Game Guide versions for any official or unofficial Game Guide

Therefore, creating each mod page is always the prerequisite to guide creation. Mod pages only need to be created once, and many exist already on the wiki. Access the mod-page Form from the Game Portal Page of the game as indicated on the Step Portal, accessible from the top menu under Navigation > Step Portal.

When creating mod pages, most attributes will be known ahead of time, but some attributes must be back-filled later, once the curator determines interactions and conflicts in the final guide (e.g., Patch flags and Recommendations):

First, create the forum mod topic:
1. Go to the 'Mods' forum of the game for which the guide is being created.
2. SEARCH THIS FORUM for the mod in question. This is super important.
3. Create/edit the topic OP using the forum editor tool.
  
  This ensures the mod topic has all necessary information, AND it creates the convenient wiki link to create the mod page. TIP: click the link to create the mod page, and type {{mod}} as the only edit, and then save. This allows the wiki mod Form to be used on subsequent edits when clicking the pencil icon to the right of the Tools menu in the navbar.
4. Add any applicable special instructions or screen compares below the horizontal rule.
Always use the mod source 'full' mod name by pasting the mod name directly from the source (do not edit otherwise but see following exceptions). E.g., this mod's name is copied from the Nexus breadcrumb at top of page and includes underscores. This is not ideal, but it is what it is. If the mod author cleans up the mod name, staff will 'move' the existing mod page to the new name upon request.
Always assign the 'best' ModGroup name to the mod. This should match the forum topic tag and will determine placement of the mod in the guide. Use the following guidance:
- Use the most appropriate 'logical' ModGroup by understanding the mod itself. E.g., SKSE mods can be Extenders, Resources, Fixes, etc., but can NEVER be "Models and Textures".
- If > 1 ModGroup applies, choose the one that achieves the simplest result in terms of conflict resolution (minimize the need to hide files in MO), usability, and instruction.
Complete ALL other 'knowable' information (Recommendations and flags will usually be added later)

Mod Recommendations

Mod installation instructions are needed by roughly 40% of all mods. They provide the 'recommendations' for mods via collapsible 'ModGroup' tables in guides. Recommendations can exist on the mod page itself ('base') or on version-specific subpages of the mod page. This enables the use of variable installation instructions by guide version. The 'base' Recommendations are really just the 'first' created for a particular guide, and these almost always apply to all subsequent guide versions.

Mod page wiki markup reference

NOTE

Mod pages should NOT use wiki headings, because they will appear in Guide-level ToC. Likewise, avoid using Templates in mod Recommendations wherever possible to avoid the wiki transclusion limit in guides (exception: Template:Fomod). On average, there should be << 1 Template call per mod page (preferably < 0.5/mod page). See details

Version-Specific Recommendations

All mod pages have the ability to append both 'base' and version-specific mod Recommendations that pertain to one or more guides but not necessarily all of them. The 'base' recommendations are implemented until a new guide needs to deviate. Version-specific mod Recommendations are only necessary when a specific version of a mod pertains to specific guide versions (and that mod version remains available from the source). This will most frequently happen with the Step patches, because they are hosted on the Nexus by Step, and will always be available for previous guide versions.

The version-specific instructions of, say the 3.0.0 guide, may instruct download of the 3.0.0 Step Patch, while the 3.1.0 guide could point to the 3.1.0 version. In this way, both patches can be maintained for their respective guides, and the corresponding Recommendations can coexist on that mod page even though they are slightly different for each guide. See any mod page for instructions on creating/maintaining these version-specific Recommendations (TIP: When on a mod page, hover over the small icons to get more information):

Step 2: Create Game Concepts

The SMW "Concept" is a query on a page in the Concept namespace that essentially behaves like a dynamic Category. These are handy in that they allow associating pages using SMW queries (against Categories, properties, and more) rather than using multiple Categories per page, which in turn is considered 'bad' practice on any SMW-powered wiki.

NOTE

Having pages with multiple Categories is acceptable where truly necessary, but they are strictly minimized on this wiki. Please note the existing Category hierarchy, and vet any proposed changes or additions with z929669

Talk. Many Category assignments are set by Templates used by Forms.

This wiki uses Concepts to associate ModGroup mods by 'Game' and is thus important for differentiating Game Guides and associated ModLists. Since Step supports several games, each having 21 distinct ModGroups, creation of hundreds of Concept pages becomes tedious and challenging. Form:CreateGameConcepts is used to simplify and reduce potential error; although, it is still a minorly tedious process. For each listed Game, each of the 21 Concept pages must be iteratively created using the Form. Fortunately, this only needs to be done once for each game Concept. Game portal pages indicate whether or not this has been done yet for the corresponding game.

Step 3: Update SMW Metadata

NOTE

This step applies ONLY to official guides. Ask a staff person to accomplish the equivalent result for an unofficial guide. Please provide the wiki page name of the current guide and the intended version # of the guide under development.

This step will need to be completed by staff or other members of the wiki 'Step' group role. It involves updating the current and development version of the Game Guide on the Step Portal to facilitate guide/changelog propagation.

Step 4: Create/Update ModList

The 'ModList' is the heart of the guide-level metadata and tells guides how mods should be ordered within each ModGroup table of the final guide. The ModList page also displays relevant mod metadata for convenience.

Once all mods have been added and the next version of the guide is known and its version metadata updated on the wiki, the ModList can be assembled using the ModList management tool at the bottom left of any game portal page, which is in turn accessible from the Step Portal.

Simply follow the instructions to create/edit the ModList page. Opening this page can take up to one full minute for existing, large mod lists, so please be patient.

Once the ModList opens, a drag & drop interface is presented with each ModGroup shown as a tabbed heading. For each section, begin typing in the mod name for a relevant mod belonging in that ModGroup. Autocomplete will aid in selection of the intended mod. Select the mod and click [Add] to add it. Repeat to add other mods into the ModGroup. Once added, mods can be reordered using drag & drop.

Alternatively, ModLists can be edited using the source editor accessible under the ellipse to the right of the 'edit' asterisk at the top right of the page itself. The source editor opens quickly, regardless of how many mods are in the ModList, since it bypasses the template calls that would otherwise render the page HTML. This can be more conveniently edited by those that understand the format and don't break it upon editing.

Step 5: Propagate Guide/Changelog

At this point, most of the heavy lifting for the guide is complete. From here, it's all about fine tuning guide (and mod) instructions.

For official guides, a propagation/edit tool exists to facilitate for both the guide and the changelog. This tool is at the bottom right of any game portal page, which is in turn accessible from the Step Portal:

As described in the instructions, unofficial guides must be manually copied into the new guide/changelog page. Please ask staff for assistance if the instructions are not understood, and have the existing/new guide version #s handy.

Step 6: Modify Guide/Changelog

As with mod pages, once created, the development guide and changelog pages can simply be edited like any other page. These should be as close as possible to the desired result, since they are copies of the current versions. For general tips on editing Step wiki pages, please see our Wiki Maintenance Guide.

Step 7: Publish Guide

Once the Guide is complete and ready to be published, return to the Step Portal and click the button for Guide Versioning:

On the versioning page,

Find the guide that needs to be published
Change the GameName line to the version that is being published
Change the GameName DEV line to the next version that will be released
For example, if the version being published is v1.1.0, then make GameName 1.1.0 and change GameName DEV to 1.2.0
Click [Save page] at the bottom of the form when complete

These steps will amend the headers implemented on the guide page; removing the "development warning" and applying the "current release" header. At this point the guide is published on the wiki; however, don't forget any supporting file updates (like guide patches) and forum changes that may be desired to support the new guide release.