Template talk:Assignmentinfo/TrajosProposalNov19

Big text Here is my proposal about adopting some guidelines regarding creating/editing assignment pages, most of which should contain this template Assignmentinfo.

Objectives Behind Proposal
Before the actual proposal, it is worth outlining what drives me to make that proposal. The overall goal is to make this website THE go-to number 1 resource for anything STO-related, while maintaining a friendly and cooperative environment among the fellow editors.

It is important to agree on the goal/objectives first, so we can discuss on how to best reach them. I believe that goal can be achieved by fulfilling the following objectives, in roughly decreasing order of priority (i.e. highest priority at the top).
 * Comprehensiveness. Provide comprehensive content sought by an average reader.
 * This includes providing as much content, as is possible to extract out of STO. Readers are less likely to be interested in a website that gives them little details beyond generalized summaries or personal opinions, not backed up by any official STO data.
 * Without needlessly omitting or shortening the key details, e.g. provide the full numerical value of CXP reward without rounding it, and with including information that may only apply to a subset of readers, e.g. PC-only or Xbox-only information.
 * Accessibility. Make the content easily accessible.
 * Even the best page in the world is useless, if users cannot get to it. All pages should be considered to be listed on any appropriate "table of contents"-type of pages/page footers, such as Dilithium/Assignment chain footers
 * Each page should be named and have such contents as to be readily available from using search (ideally from autocompletion dropdown), without having to click through multiple pages before reaching the desired one.
 * Any pieces of information that are likely to be related - i.e. those the user may want to compare should be consolidated in one page and not scattered across multiple pages.
 * Presentation. Make the content well presented, and easy to read.
 * Make it easy for readers. Keep the workflow of an average reader in mind, and structure the presentation appropriately.
 * Including the use of any visual GUI aids, such as text highlighting, tables, icons etc. Readers are more likely to be interested in a website using visual aids appropriately, rather than a text-only one.
 * If something is unclear or ambiguous - discuss with fellow editors and establish new guidelines. E.g. do we need to have both tier and level fields? Do we need to have a separate icon for faction=Both that omits Romulan icon vs faction=All that includes it?
 * Cooperation. Respect fellow editors and readers.
 * Follow agreed guidelines to avoid generating unreadable/unreachable content that would turn readers away, and also to avoid disappointing fellow editors.
 * Assume good faith of fellow editors - and don't amend information that has been recently added/modified by a fellow editor without reaching out to them first. How far back is "recently" - to be agreed.
 * Do not replace existing details unless you have a strong reason to believe your new details are more reliable. E.g. don't replace existing official/confirmed details with ones obtained via estimation. (However for new content - estimates are totally acceptable, better have something than nothing at all.)
 * Maintainability. Make the pages easily maintainable in the future.
 * Make it easy for yourself and fellow editors. Game information has a tendency to change over the course of years, and someone will be updating those pages. Either us, or the new editors that will be active in 1, 2, 3 years from today. Whoever it is - let us make their life easier, where it won't harm the preceding higher priority objectives.
 * Optimization. Last, but not least - Use wiki features appropriately.
 * E.g. try to use as few templates as possible, including avoiding using formatting templates in values of simple fields, when the enclosing template can be modified to format the field, such as "Casualty Risk".
 * Keep technical side effects of your modifications in mind. E.g. sufficient testing for any template modifications to avoid breaking formatting on other pages or cargo storage.

Concrete Proposals
Here are the concrete proposals to facilitate reaching the above objectives.

Assignmentinfo Fields

 * rewardtype
 * Yes, this is useful, thanks for adding this, I will endeavor using it whenever possible. A possible improvement could be to have the template automatically infer that out of rewards field by doing a text search for common keywords, as the way things are at the moment - this is essentially duplicated between reward and rewardtype fields. I will see if I can code it up.
 * faction
 * I propose not to have separate icon for faction=Both that omits Romulan icon vs faction=All that includes it. I would just make Both to behave as All, i.e. always include Romulan icon. Additionally, there appear to be no Assignments that would be available for e.g. KDF captains, but not available to KDF-aligned, so I would modify FED and KDF icons into FED-plus and KDF-plus.
 * loctype
 * This should be split into platform-specific fields, e.g. loctypepc, loctypexbox. For PC this should be used to list the name of GUI tabs, where an assignment is to be found. Having a wikipage giving a lot of information about an assignment has little benefit, if the user does not know where in the game they need to look for it.
 * An alternative is to list values in the single loctype field, suffixing each value with platform information, such as Current Page (PC), Very Rare (XBox).
 * tier
 * From template doc this appears to duplicate level, in which case it should be removed.
 * outcomes
 * PC editors should have priority in updating these details, as a game limitation on other platforms makes it cumbersome to extract these probabilities. On PC players have a GUI tickbox "Enable First Officer Recommendations" that when unticked - will show the base probabilities. On other platforms that tickbox is not on the GUI and instead STO behaves as if it is always ticked. Workarounds exist, but they involve sourcing specific DOffs to be assigned, and even then the probabilities seem to be off sometimes by 1-2%. Regarding the hypothesis It should also be noted that obtaining outcome percentages in that manner (with duty officers slotted) is effectively more accurate - completely disagreed, once anything is slotted - you are no longer looking at base outcomes, you are looking at outcomes modified by those officers. I want to be able to derive a formula that can give me final outcomes, but for that I need precise base outcomes, not outcomes with something slotted - where the formula has already transformed the outcomes into the output ones. Simple example proving that slotting anything in causes the game to no longer display base outcomes: Assignment: Relocate Colonists.
 * The list of outcomes appear to differ sometimes between platforms, e.g. XBox might have 4 outcomes, and PC only 3 without the "Disaster" for certain assignments. In this case I think it is acceptable to list the outcomes from the maximum platform (XBox), and in the notes list them and their base probabilities from the minimum platform (PC), with a footnote capability being added to this template.
 * risk
 * This is a simple field that should not use any templates in it, especially for formatting. This template will automatically format this field depending on the value, and by using simple text we will be able to run cargo queries on it (e.g. generate a table of all assignments with None risk etc.)
 * doffs/cost
 * One presentation-related controversy regarding these is the positioning and spacing of the multiplier. Should it be 2x Any duty officer, or 2 x Any duty officer? 2 x Any duty officer, or Any duty officer x 2? I prefer the prefix variant, as it is a shorter part that is easier to digest before the longer part; leaving the multiplier at the end makes it easier to be overlooked after reading the longer "Any duty officer" part. A single space before and after "x" makes it easier to read still. Icons should be used here, even though they are not used in game, as per "Presentation" principle - to aid the reader in quickly understanding the requirements before they have read the text. Few prefer text-only websites to ones with icons and other visual aids.
 * cxp/sp/bosp
 * Values that can be used here are very ambiguous, as there is one value that is shown on in-game assignment information pre-start page, but once an assignment completes - the reward differs randomly between toons for no obvious reason. My proposal is to always use the values from in-game assignment information pre-start page, as at least - they are not random, and hence can be useful for 2 things: comparing rewards from different assignments, and also trying to reverse-engineer the formula used to calculate the final reward value from the input value.
 * name
 * I would really like to talk about the page name here, as the value used in this field did not seem to be a matter of debate - it should simply match the name of the in-game assignment, if the page refers only to a single one, or should include variable parts, if the page describes several similar assignments such as " Colonists to ". Should the page name include variable parts if a single page is used for multiple assignments? Examples are: Assignment: Relocate Colonists, Assignment: Barter Gold-Pressed Latinum, Assignment: Relieve Minor Shortfall of Gamma Quadrant Commodity. I propose that whatever naming convention is chosen, there should be redirect pages to the actual destination assignment page, with each redirect page having the name exactly as the assignment name appears in game. E.g. "Assignment: Relocate Colonists To Fedetaion Borders" and "Assignment: Deport Colonists To Imperial Perimeter", should be both redirect pages to "Assignment: Relocate Colonists" that actually houses the assignment page.  In addition, the main page could be more descriptive, if this does not cause abmiguity, e.g. "Barter Gold-Pressed Latinum for Commodity". However, if an ambiguity is present, as e.g. with "Haggle for Gamma Quadrant Commodity", or "Haggle for Rare Commodity" - either the more generic version should always be used, i.e. the "Haggle for Commodity" (as a larger proportion of readers has encountered at least one commodity, whereas encountering a "Gamma Quadrant" commodity requires considerably more experience with the game), or if no version is more generic than the rest - the variable part of the name should be omitted altogether, e.g. just "Haggle".
 * rarity
 * Perhaps this is the most controversial of the fields, as this field is linked to the practice of creating a separate page for the separate rarity of an assignment. Examples are Assignment: Barter Gold-Pressed Latinum, Special Deal on Entertainment Provisions and Assignment: Relieve Minor Shortfall of Gamma Quadrant Commodity. As I said earlier, I much prefer to keep all information regarding different rarity variants of the same assignment on one page. Rationale? Easier to compare assignments when I am deciding which ones I want to pick from a list, as the examples mentioned are often presented on the same list in-game. Having to open 3-4 tabs and switching between them is very inconvenient. Additional difficulty is that there is a lot of duplication between pages, so either 4 different tabs need to be updated once game information changes, or one tab gets updated, and the other 3 - will invevitably get neglected. The next question that I anticipate would be: how do we present the information about all the different variants of the assignment on a single page, using a single Assignmentinfo template? Answer: in the template we will list the range of values, e.g. "rarity=Common - Very Rare", then in the body of the page we will have a table listing all the different rewards for different rarities. Here is a sample mockup:
 * Where similar assignments differ by assignment rarity, as the STO wiki categorizes those in that manner, they should be kept separate. - I disagree, as the cluttering while a drawback, is incomparable to the drawback of only having part of the sought information on Assignment: Barter Gold-Pressed Latinum, the other being scattered across 4 different pages, one for each rarity. Having all info on one page has a further significant advantage of allowing the player to easily compare and select which of the assignments they wish to pursue given the rewards and the limit of 20 assignment slots. A similar argument applies to 3 different rarities of Assignment: Relieve Minor Shortfall of Gamma Quadrant Commodity. I want to know which assignment gives the best return for my hard-earned rare commodities. Thus keeping all information on a single page is a win-win for both readers, editors that only need to update 1 page not 4, and the website that will have less neglected pages that were forgotten to be updated.

Contents

 * Related assignments
 * If certain assignments are closely related, but a bit too different to be represented on a single page, example: Assignment: Formal Gift Exchange and Assignment: Black Market Provisioning, using template should be encouraged to link to related assignments:


 * This should not be used where there is no ambiguity. - Can you please give an example, and also reasons why it should not be used?


 * Possible locations
 * The map generated by should not be used if an assignment is universally available, such as Assignment: Confiscate Contraband From Crew, Assignment: Dilithium Mining in an Unstable Asteroid Cluster, or Assignment: Relocate Colonists. This includes if an assignment is universally available only in either space or ground maps, such as Assignment: Resettle Colonists that is universally available on any system or sector space map. Otherwise, a map should be included, to indicate either on which map the assignment will be automatically added to player's assignment window, or where to find the NPC that gives out this assignment, such as Trade on DS9 for Barter/Haggle assignments. This includes a case when an assignment is only available in a single location, such as Assignment: Haggle for Gamma Quadrant Commodity as it would firstly immediately make the user aware that this is not a page for a universally available assignment, and secondly it provides a visual aid of the map to show - to aid the reader in quickly understanding where exactly in game the assignment can be found before they have read the text. Few prefer text-only websites to ones with maps and other visual aids.
 * Ordering of sections
 * Multiple variations exist, so my proposal is to make them all consistent as follows:
 * - optional, if there are any related assignments
 * Editor's summary - optional
 * ==Summary==: In-game text for each variant of the assignment covered by this page
 * ==Variations==: Description of variations of this assignment (factions, rarities etc)
 * ==Outcome==: In-game text for each outcome
 * ==Rewards==: Table of rewards for different variations of this assignment
 * ==Requires==: Detailed requirements, including success/failure traits with icons
 * ==Possible locations==: Text and/or showing where to find this assignment
 * ==Notes==: Any additional information that does not fit anywhere else. E.g. "Even using duty officer with failure traits always makes success outcome chances to add up to 100%, hence this assignment appears to be impossible to fail."
 * ==Notes==: Any additional information that does not fit anywhere else. E.g. "Even using duty officer with failure traits always makes success outcome chances to add up to 100%, hence this assignment appears to be impossible to fail."