STEP:Mod-Build Guide Framework: Difference between revisions

From Step Mods | Change The Game
mNo edit summary
Tag: Manual revert
 
(24 intermediate revisions by 2 users not shown)
Line 1: Line 1:
__NOTITLE__[[Category:Step Wiki Guides]]{{PageTitle|logo=delta|title=Mod-Build Guide Framework|subtitle=Understanding Step's framework for creating and maintaining mod-build guides|author=Step Modifications|forumtid=}}
__NOTITLE__[[Category:Step Wiki Guides]]{{PageTitle|logo=delta|title=Game Guide Framework|subtitle=Understanding Step's framework for creating and maintaining Game Guides|author=Step Modifications|forumtid=16167}}
{{Alert|type=construction|text=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.}}{{TOC right}}
{{Alert|type=construction|text=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.}}{{TOC}}
This wiki makes use of [https://www.semantic-mediawiki.org/ Semantic Mediawiki] (SMW) to facilitate the functionality needed for the 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.
For those interested in using our framework, please also refer to some basic guidelines (and rules) for curating content on the Step wiki:
* [[Guide:Wiki_Maintenance|Step Wiki User Guide]]
* [[Project:SiteColorPallet|Step Wiki Color Pallet]]


Step has many guide types, but most notable are guides for [[Property:Game|supported games]]. This documentation applies to these guides specifically. For assistance with any step(s) in this process, please contact [https://stepmodifications.org/forum/staff/ site administrators].
This wiki makes use of [https://www.semantic-mediawiki.org/ 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 [[Property:Game|supported games]]. This documentation applies to these guides specifically. For assistance with any step(s) in this process, please contact [https://stepmodifications.org/forum/staff/ site Administrators or Step Admin].


Step has built out an improved guide-creation infrastructure that confers the following important benefits to guide curators:
Step has built out an improved guide-creation infrastructure that confers the following important benefits to guide curators:
Line 23: Line 27:
* Allow title/instruction/attribute 'tansclusion' into ModList and guide tables
* Allow title/instruction/attribute 'tansclusion' into ModList and guide tables
* Make mods available to mod list queries/exports
* Make mods available to mod list queries/exports
* Can be reused across game-guide versions for any official or unofficial mod-build guide
* 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:Main|Step Portal]].
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:Main|Step Portal]].
Line 36: Line 40:
*:# Nexus ID# (exclude mods that are not on Nexus under the game of interest)
*:# Nexus ID# (exclude mods that are not on Nexus under the game of interest)
* '''Always assign the 'best' [[Property:ModGroup|ModGroup]] name to the mod.''' This will determine placement of the mod in the guide. Use the following guidance:
* '''Always assign the 'best' [[Property:ModGroup|ModGroup]] name to the mod.''' This 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 & Textures".
** 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.
** 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)
* '''Complete ALL other 'knowable' information''' (Recommendations and flags will usually be added later)
Line 42: Line 46:
*# Go to the 'Mods' forum of the game for which the guide is being created.
*# Go to the 'Mods' forum of the game for which the guide is being created.
*# SEARCH THIS FORUM for the mod in question.
*# SEARCH THIS FORUM for the mod in question.
*# Create/edit the topic OP using the 'source' editor (use the [[STEP:Mod_Topic_Boilerplates|boilerplate source]] to facilitate)
*# Create/edit the topic OP using the forum editor tool. [[File:Ckeditor-modtopic.JPG|600px|right]]
*# Add any applicable special instructions or screen compares below the horizontal rule.
*# Add any applicable special instructions or screen compares below the horizontal rule.


=== Mod Recommendations ===
=== 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 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.
{{Alert|text=Mod pages should NOT use wiki headings, because they will appear in Guide-level ToC. Instead, use:<br> <code><nowiki><p>'''BOLD, ALL CAPS'''</p></nowiki></code><br> for headings. 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).}}
* Mod page wiki markup [[Guide:Wiki_Maintenance#Mod_Pages|reference]]
{{Alert|text=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). [[Guide:Wiki_Maintenance#Mod_Pages|See details]]}}


==== Version-Specific Recommendations ====
==== 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 used 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.  
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 [https://www.semantic-mediawiki.org/wiki/Help:Adding_tooltips icons] to get more information):
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 [https://www.semantic-mediawiki.org/wiki/Help:Adding_tooltips icons] to get more information):
Line 58: Line 64:
The SMW "[https://www.semantic-mediawiki.org/wiki/Help:Concepts 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.  
The SMW "[https://www.semantic-mediawiki.org/wiki/Help:Concepts 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.  
{{alert|text=Having pages with multiple Categories is acceptable where truly necessary, but they are strictly minimized on this wiki. Please note the existing [[Special:UncategorizedCategories|Category hierarchy]], and vet any proposed changes or additions with [[User:z929669|z929669]] [[File:Ixian_Insignia.png|20px|link=User:z929669]] [[User talk:z929669|Talk]]. Many Category assignments are set by Templates used by [https://www.mediawiki.org/wiki/Extension:Page_Forms Forms].}}
{{alert|text=Having pages with multiple Categories is acceptable where truly necessary, but they are strictly minimized on this wiki. Please note the existing [[Special:UncategorizedCategories|Category hierarchy]], and vet any proposed changes or additions with [[User:z929669|z929669]] [[File:Ixian_Insignia.png|20px|link=User:z929669]] [[User talk:z929669|Talk]]. Many Category assignments are set by Templates used by [https://www.mediawiki.org/wiki/Extension:Page_Forms Forms].}}
This wiki uses Concepts to associate ModGroup mods by 'Game' and is thus important for differentiating mod-build guides and associated ModLists. Since Step supports several games, each having [[property:ModGroup|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.
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 [[property:ModGroup|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 ==
== Step 3: Update SMW Metadata ==
{{Alert|text=This step applies ONLY to official guides. Ask a [https://stepmodifications.org/forum/staff/ staff person] to accomplish the equivalent result for an unofficial guide. Please provide the wiki page name of the current guide and the intended [[STEP:Versioning|version]] # of the guide under development.}}
{{Alert|text=This step applies ONLY to official guides. Ask a [https://stepmodifications.org/forum/staff/ staff person] to accomplish the equivalent result for an unofficial guide. Please provide the wiki page name of the current guide and the intended [[STEP:Versioning|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 mod-build guide on the [[STEP:Main|Step Portal]] to facilitate guide/changelog propagation.
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:Main|Step Portal]] to facilitate guide/changelog propagation.


== Step 4: Create/Update ModList ==
== Step 4: Create/Update ModList ==
Line 86: Line 92:


== Step 7: Publish Guide ==
== Step 7: Publish Guide ==
Process steps pending ...
Once the Guide is complete and ready to be published, return to the [[STEP:Main|Step Portal]] and click the button for Guide Versioning:
[[File:VersioningUpdate.png|805px|frameless|border]]{{clear}}
 
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 {{ui|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.

Latest revision as of 04:33, March 1, 2024

Delta c.png

Game Guide Framework

Understanding Step's framework for creating and maintaining Game Guides

by: Step Modifications  | Forum Topic

Weapon.png

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
Info-Logo.png

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[edit | edit source]

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):

  • SEARCH THE WIKI FOR THE MOD! There is no need to create what already exists. TIP: Autocomplete effectively 'searches' for existing mods within the GameSpace.
  • 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.
    >> Exceptions: Administrators can create wiki mod pages in bulk if the Curator provides a tab-delimited text file containing the following:
    1. Mod Name (Special chars, apostrophes, and parentheses should be removed from pasted mod names for this process to work)
    2. Mod Author(s) (comma separated if multiple)
    3. ModGroup (see below)
    4. Nexus ID# (exclude mods that are not on Nexus under the game of interest)
  • Always assign the 'best' ModGroup name to the mod. This 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)
  • 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.
    3. Create/edit the topic OP using the forum editor tool.
      Ckeditor-modtopic.JPG
    4. Add any applicable special instructions or screen compares below the horizontal rule.


Mod Recommendations[edit | edit source]

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.

Info-Logo.png

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[edit | edit source]

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):

Gude-Version-Specific Mod Recommendations.jpg

Step 2: Create Game Concepts[edit | edit source]

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.

Info-Logo.png

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 Ixian Insignia.png 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[edit | edit source]

Info-Logo.png

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[edit | edit source]

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.

Create or Edit ModList.PNG

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[edit | edit source]

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:

Propagate or Edit Guide.png

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[edit | edit source]

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[edit | edit source]

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

VersioningUpdate.png

On the versioning page,

  1. Find the guide that needs to be published
  2. Change the GameName line to the version that is being published
  3. 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
  4. 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.