diff --git a/src/SUMMARY.md b/src/SUMMARY.md index f0a2fa9b02..57a5551913 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -36,11 +36,9 @@ General Development - [Config File Reference](en/general-development/tips/config-file-reference.md) - [YAML Crash Course](en/general-development/tips/yaml-crash-course.md) - [Forking Tips](en/general-development/tips/forking.md) -- [Feature Proposals](en/general-development/feature-proposals.md) - - [Feature Proposal Template](en/templates/proposal.md) - - [Expected Team Decorum & Usage](en/general-development/feature-proposals/expected-feature-proposal-decorum.md) +- [Design Documents](en/general-development/design-documents.md) + - [Design Document Template](en/templates/proposal.md) - [Work Groups](en/general-development/work-groups.md) -- [Game Area Design Documents](en/general-development/game-area-design-doc.md) - [Contributing Translations](en/general-development/contributing-translations.md) - [Github Moderation Guidelines](en/general-development/github-moderation-guidelines.md) diff --git a/src/en/general-development/codebase-info/pull-request-guidelines.md b/src/en/general-development/codebase-info/pull-request-guidelines.md index bbfa0327b6..0d8a72282b 100644 --- a/src/en/general-development/codebase-info/pull-request-guidelines.md +++ b/src/en/general-development/codebase-info/pull-request-guidelines.md @@ -15,7 +15,7 @@ Your pull request may be reverted or closed for any reason. - Please have some familiarity with [C# conventions](https://docs.microsoft.com/en-us/dotnet/csharp/) (if working with C#) and [our own conventions](./conventions.md). Try to read how other parts of the codebase are formatted for a general idea. -- Large new features and comprehensive reworks to existing large features (ie antags or anything that could be considered a subdepartment unto itself), should first be [proposed and accepted in abstract](../feature-proposals.md) before you start working on actually implementing it. +- Large new features and comprehensive reworks to existing large features (ie antags or anything that could be considered a subdepartment unto itself), should first be [proposed and accepted in abstract](../design-documents.md) before you start working on actually implementing it. - Read the [Freezes and Restrictions issue](https://github.com/space-wizards/space-station-14/issues/8524) and make sure your PR does not interfere with anything or requires special requirements. diff --git a/src/en/general-development/design-documents.md b/src/en/general-development/design-documents.md new file mode 100644 index 0000000000..82c9903393 --- /dev/null +++ b/src/en/general-development/design-documents.md @@ -0,0 +1,126 @@ +# Design Documents and Proposals +Design documents outline or guide a game area, department, mechanic, or system design. +They are extremely important for organizing SS14's development. + +Overall, a design document seeks to achieve the following goals: +1. **Design documents are important for establishing a general direction and working towards a vision.** + 1. It is useful for contributors and maintainers to know whatever you're thinking, and how your feature will fit into the game. + 2. Sometimes things are simply incompatible with a previously existing design or goal, and we don't want you to waste your time making something that has to be rejected at the end of the day. Similarly, you shouldn't write a feature to completion and then attempt to write a design document that justifies your added feature. This usually results in a lot more wasted time. + 3. It is essential that ideas, problems, solutions, etc. do not get lost to time. SS14 has been burned in the rear by people forgetting *why* we made a decision, going down a path we already found out the hard way as to why it doesn't work. As such, design documents serve as a way to outline your reasoning and preserve your thought process as to why something exists. +2. **Design documents inform the players and contributors as to how something should be.** + 1. Not everyone knows what you're thinking, and sometimes it's tiring explaining your idea over and over again. By explicitly outlining your intentions and goals, people will be more comfortable following through with your idea. +3. **Design documents allow you to think about your design critically and with other people.** + 1. It's best to write down what you intend to do/solve somewhere instead of winging it first try after you asked around. This also allows fellow contributors to review your ideas, offer advise, compliment your design, or point out issues. + +As such, we highly encourage you to write a design document if necessary. +This page should tell you everything you need to know if you're considering writing one - be sure to read it fully. + +## Writing design documents +These further sections outline what should be seen out of a design document. + +### Do I need to write a design document? +It depends on where your goals align in the following section. In general, if you're adding a major roundflow element, department mechanic, antagonist, or other large feature, you should consider making a design document. + +Minor features shouldn't need a design document, but instead use existing design documents to justify their addition when a pull request is made to the content repository. + +### Design documents should be tiered +Design documents should be structured in a way so that each design document is derived or supported by the design document that came before it. +This cuts down on having to explain *why* game design elements are beneficial, and instead focus on *how* your design satisfies what is desired out of a feature. + +In general, higher-level design documents should outline base gameplay and very general principles that designs under them should try and follow. Lower-level design documents would then outline features, mechanics, or other gameplay that try to satisfy said principles. + +For example, take the following dependency tree: +```mermaid +flowchart TD; + core[Core Design Principles] + department[Departments] + + departmentEngi[Engineering] + power[Power] + engine[Engine Containment] + + departmentMed[Medical] + chem[Chemistry] + + roundflow[Roundflow] + + crew[Crew] + + antags[Antagonists] + tots[Traitors] + thiefs[Thiefs] + xenoborgs[Xenoborgs] + pursuer[Pursuer] + + core --> department --> departmentEngi + departmentEngi --> power & engine + + department --> departmentMed --> chem + + core --> roundflow + roundflow --> crew & antags + antags --> tots & thiefs & xenoborgs & pursuer +``` + +In this instance: +- The core design principles would outline general goals that designs should fulfill. + - For example, department mechanics should be engaging, promote social behavior, and work towards chaotic gameplay. +- The department design document would outline how the department fulfills these ideas. + - How do departments interact with players? We need to promote social behavior, so there should be some form of interdepartmental cooperation. + - How should departments structure their gameloops? Should departments work around mechanics that are available to everyone? +- The *specific* (engineering in this case) design document would then outline how the department establishes itself as a department. + - This is a good place to talk about a department's "theme" and what players are expected to do, and what mechanics they'll be interacting with the most. + - Maybe Engineering is getting their hands dirty most of the time, with gameplay being repair-focused and keeping up with station degradation. + - Maybe engineering is tasked with powering the station - how is powering the station engaging, and how does it promote interdepartmental cooperation? +- The later design documents would now outline features that satisfy the goals the department design document set out. + - Engineering wants repair-focused gameplay, so what does this gameplay look like? Things like a "machine repair" design document and a "station degradation" design document belong here. + - Engineering needs to power the station. How will they power the station? What does power look like? How will the crew interact with power? + +### Design documents should defend themselves +The evil question of doom is approaching, and they have some choice words for you: Why are you doing what you're doing? + +Design documents should ultimately work towards a goal, and part of that work is justifying the changes you're making, and how they contribute to your goal. +Documents shouldn't be a feature list that simply describe a list of abilities an antagonist has, or what mechanics a department has. +These abilities should come with justifications that outline _why_ these abilities are being designed this way, and how they contribute to your goal. + +For example, take the Pursuer design document, an antagonist that establishes itself as a furious robot dude that chases a poor soul down and seeks to kill them. +The document explicitly outlines the _theming_ of the antagonist, and the antagonist's goals: + +> The Pursuer is a midround antag focused on creating a short duration of high-intensity action for part of the crew, while keeping its overall station impact is relatively low. One crewmember is selected as the Pursuer’s target and must evade capture long enough for the Pursuer to be killed, either via the assistance of other crewmembers or a natural timer on the Pursuer’s end, while the Pursuer aims to kill and gib the target through various brute-force methods. The Pursuer is designed to be loud, intimidating and bulky, with a ramping strength that pushes towards an exciting climax. + +In this, we've already outlined a few goals: +- The antagonist adds a spike of chaos while not being extremely problematic to the point where it causes the station a lot of trouble. +- The pursuer has a single target and must kill it or else it runs out of time. We expect the crew to either intervene or the player to hold a PhD in running away from things. +- The theming of the antagonist is established - it's a terrifying hunk of metal, and it wants to kill you. + +The document then describes a list of features, but makes sure to say why those features are necessary and how they work towards the established design goal. + +### Design documents should not delve into technical implementation details +Design documents seek to establish what your design is, why you're doing what you're doing, and how it should be produced. +As such, design documents should try to stray away from how a feature will be implemented technically. +This is often irrelevant to a design document - contributors want to know how to create more features or mechanics that align with your design goals, not how to code them. +In general, this guideline is less strict as you start to move closer to a low-level design document that's outlining a concrete feature. +Core design principles or higher-level design documents shouldn't be delving into technical details. + +For example, a Traitors design document should never, ever, outline how `StealthSystem` is used for making a lot of invisible stealth-based traitor equipment. +Instead, the document should elaborate on how traitors are expected to use stealth equipment. +Do they use it offensively? Defensively? How expensive should the equipment be? +Should it be a get-out-of-jail-free card, or something that requires careful planning? + +This is especially true for design documents that put focus on how players express creativity, or mechanics designed around players making creative combinations from available mechanics. +For example, the Atmospherics design document outlines how devices should not perform everything all in one device, rather devices should perform one operation at a time: + +> Atmospherics and its mechanics, tooling, and devices should perform small unit operations, or single tasks, with multiple devices coming together to form a larger system. Just like how all logic gates (and computers in general) are built off of the universal logic gates `NAND` and `NOR`, atmospheric systems are built via the combination of smaller devices. +> +> This allows for a wide variety of solutions to problems and encourages players to think creatively about how to solve them. There should rarely be a single “correct” solution to a problem, instead players should be able to come up with their own solutions based on the tools available to them. + +It _does not_ go into detail as to how these devices will be split on a technical level, how they interact with each other using `NodeContainer`s, how they transfer gas to each other using `PipeNet`s, etc. +Those are all implementation details that are determined when PRing the feature. + +### Design documents should not be written as if the feature already exists +Design documents should be written from the perspective of someone who hasn't interacted with your feature before. +We can't see inside your head, or what you've personally experienced. +The person reading the document needs to know the _context_ and surrounding _events_ that drove you to make the decisions that you made. + +- If your design document is explicitly designing around bad gameplay, it should state what that gameplay was, why it was bad for the game, and how the new design plans to resolve the previous issues. +- If your design document mentions that a similar design existed in SS13, you should *really* take advantage of whatever lessons that were learned (or lack thereof) in SS13. Mentioning that a feature "existed in SS13" shouldn't be used as automatic justification for a feature existing, as SS14 is different and lacks a lot of the surrounding mechanics and context that might have made a design good in SS13. diff --git a/src/en/general-development/feature-proposals.md b/src/en/general-development/feature-proposals.md deleted file mode 100644 index 3b38b6c0f9..0000000000 --- a/src/en/general-development/feature-proposals.md +++ /dev/null @@ -1,52 +0,0 @@ -# Feature Proposals - -If you are considering adding or reworking some major component of the game it's recommended that you submit a proposal before you actually start coding whatever it is you want to do. Pinning down exactly how your feature should work to mesh well with the rest of the game will save you a lot of headaches rewriting your PR for the ~~1st2nd4th~~ 7th time before it gets merged. - -## How do I make a proposal? - -1. Make a copy of the design proposal template located at `src/en/templates/proposal.md`. - -3. Read through [SS14's Core Design Documentation](../space-station-14/core-design.md) (for gameplay-related proposals). - -4. Write your proposal (see [guide to editing docs](../meta/guide-to-editing-docs.md)). - -5. When you are ready for your proposal to be reviewed, make a pull request. - -6. Your proposal is approved when a maintainer merges it. This is a green light for you or someone else to go ahead and implement it. A maintainer will then link your proposal to the side bar. *Note to maintainers: edit `src/SUMMARY.md`* - -``` admonish tip "Unfinished Proposals" -If you don't think that your proposal is ready for maintainer scrutiny, but still want feedback on it you can PR it as a draft. Drafts are less likely to attract people looking to get down to brass tacks, but still let people comment and give advice. -``` - -## No, as in what is a design doc? - -A design document is a high level summary of whatever you're proposing to add to the game. They basically serve to get nebulous ideas down on paper so it's easier to see how exactly those ideas will mesh with the rest of the project. They generally have a few parts. - -1. Why the feature is being proposed, which can be as simple as 'I think it would be cool' to as specific as 'I noticed ABC problems with cargos gameplay loop and want to add XYZ to remedy those problems'. -2. A high level summary of what the feature actually is, how the feature engages with players, and how the feature interacts with other major parts of the game. -3. A more detailed summary of the proposed mechanics for the feature, how players are intended to interact with those mechanics, and how those mechanics involve or are involved with other parts of the game. You don't need to go into every specific case, it's enough to say that there should be chemicals filling specific roles and not detail the exact chemicals you - -These don't have to be discrete sections and shouldn't be. When you're detailing the mechanics it's probably a good idea to detail how the players will interact with those mechanics and how the way the players interact with those mechanics benefits the game. If you want to see examples of successful design documents all of the accepted, but unimplemented, design docs can be found in the "Design Proposals" section below. Design documents that actually got implemented eventually transmute into the feature docs in the "Space Station 14" section. - -``` admonish warning "Don't" -- Include pseudocode level descriptions of how your feature works. That's for after the proposal has been accepted and you're actually implementing the thing. -- Specify numerical amounts for every item, field, or mechanic. That's for eventual balance bikeshedding; for example it's enough to say that a disease will have one, several, or many symptoms. -- Forget to include how players should interact with your features. SS14 is a multiplayer game and how the players engage with your mechanics is more important than the specific mechanics they engage with. -- Write an entire, actual FSD or SRS. It's not and will never be required as it constitutes egregious overkill for a project of our size and structure. -``` - -## Does my idea really need a design doc? - -It depends on the scale, and pervasiveness of whatever you're thinking of proposing. If it's something like adding a single gun or a couple simple plants it probably won't. On the other hand if you are adding an entire subdepartment ala anomalies/xenoarchaeology, or something on the order of reworking the entirety of botany or chemistry it certainly will. - -A good rule of thumb if the new feature or rework you have in mind would require adding or reworking a page of the guidebook or one of the feature docs on this site then it probably needs a design doc. Same if the proposal could be accurately described as 'reworking the entirety of X'. - -## Will my design doc get accepted? - -No idea! What design proposals do or do not get in is determined by maintainer approval like normal PRs. If you can get at least one maint to decide that it sounds like a good idea then there's a good chance that it will get accepted. Pretty much any idea is going to need at least some critiquing before it gets merged so don't get discouraged! - -``` admonish tip "Design Principles" -If you want to improve your chances, it's recommended that you read the [SS14 Core Design Documentation](/src/en/space-station-14/design.md) document to get a high-level overview before you start writing, as it'll provide context for why things are the way they are. - -PR'd design documents should also follow the [Decorum Guidelines](./feature-proposals/expected-feature-proposal-decorum.md). -``` diff --git a/src/en/general-development/feature-proposals/expected-feature-proposal-decorum.md b/src/en/general-development/feature-proposals/expected-feature-proposal-decorum.md deleted file mode 100644 index 53fd59b99b..0000000000 --- a/src/en/general-development/feature-proposals/expected-feature-proposal-decorum.md +++ /dev/null @@ -1,15 +0,0 @@ -# Expected Feature Proposal Decorum - -{{#template ../../templates/wip.md}} - -- No half-baked stuff or scratchbooks or anything like that. Only fully-formed documents. -- If you’re the main author of something, put your name in the title in brackets. Otherwise, note all of the authors and designers in italics under the main header. The primary designers take priority over the author of a document. -- Not everything here is gospel, or going to be implemented into SS14. If a document is authored by a maintainer or signed off by one, it can be treated as a source of truth. - -Any documents proposed: - -- Should conform to the basic [Core Game Design](../../space-station-14/core-design.md) as well as this document obviously. -- Should contain sufficient justification for their existence, -- Can be closed or drafted at maintainer discretion, -- Are a reflection of SS14 to others that may be interested in how the game is designed. Take note of that. -p \ No newline at end of file diff --git a/src/en/general-development/game-area-design-doc.md b/src/en/general-development/game-area-design-doc.md deleted file mode 100644 index 49e0ec3e67..0000000000 --- a/src/en/general-development/game-area-design-doc.md +++ /dev/null @@ -1,31 +0,0 @@ -# Game Area Design Documents & Template - -The goal of a game area design document is to provide a cohesive direction for developers that want to add or modify content in the game. New PRs should aim to align themselves with the design as laid out in the document, and Maintainers are expected to adhere to them when reviewing and discussing PRs. - -These documents are meant to be "directional" documents rather than "implementation" documents; focus should be on defining the goals and boundaries of a game area, not the specific game mechanics the player interacts with. The documents should include high-level descriptions of gameplay and the intended *feeling* players should have when interacting with the game area. - -A design document may be more or less precise depending on how large or small the game area it is covering. A general combat document may be more high-level compared to a gun weapons document, and similarly a departmental document may be more high-level than one covering just a specific role in that department. - -Below is the recommended template to use. -
-## Template -
- -# Document Name - -## Concept -> 1-2 paragraphs acting as an abstract, condensing the information of the document into an easily readable format and setting expectations for what the other sections will contain. It should provide a brief overview of the game area, but avoid to include any information that isn't mentioned elsewhere in the document. - -## Intended Experience -> A collection of simple high-level ideas that embody this game area. These are usually expressed with singluar words or short punchy phrases, but may also include a short one sentence explanation. The goal is to convey the *feeling* a player should have when playing/interacting with the game area, such that other documents and PRs can align with that intended experience. - -## Responsibilities -> A collection of points regarding what the game area is responsible for in terms of gameplay, mechanics and/or station duties. This section should highlight what unique things the game area brings to the game and simulatione. If the game area is a resource provider to the station, this is highlighted here. - -## Desired Gameplay -> A list of high-level concepts, explaining the *kind* of gameplay and mechanics we want to see in the game area's design. Each list entry should be a short sentence summarizing the design pillar with a more detailed (1-2 paragraph) description underneath. - -> While the "Intended Experience" section focuses on how it *feels*, this section's entries should focus on what the player *does*. They should still be high-level, in that you are not providing instructions on specific gameplay mechanics; they are there to act as guides when creating new mechanics or interactions, serving as the measuring posts to make sure that what you are trying to do will fit in the boundaries of the game area. - -## Undesired Gameplay -> Similar to "Desired Gamplay", but instead listing easy pitfalls and directions we *don't* want the game area to move in. This sets boundaries and helps achieve cohesion when designing new aspects of an area. diff --git a/src/en/templates/proposal.md b/src/en/templates/proposal.md index 6d03ec1cba..68dbbc4a66 100644 --- a/src/en/templates/proposal.md +++ b/src/en/templates/proposal.md @@ -1,9 +1,14 @@ # Short, Properly Capitalized Title +```admonish warning +This template isn't a fit-all. +Feel free to seek inspiration from modern design documents that already exist in the repository if you'd like to see what you need to address in your document. +``` + Your title should convey the basic jist of your proposed changes. It should be short because the text will be linked in the sidebar. -| Designers | Coders | Implemented | GitHub Links | -|---|---|---|---| +| Designers | Coders | Implemented | GitHub Links | +|-----------------|------------------|-----------------------------------------------------------------------------------------|-----------------| | your names here | coder names here | :white_check_mark: Yes or :warning: Partially or :information_source: Open PR or :x: No | PR Links or TBD | `Designers` should be the names that you, the authors of this document, use on GitHub and/or Discord. This is optional but strongly recommended, since: @@ -32,14 +37,14 @@ Summarize any information that is needed to contextualize the proposed changes, Also link any relevant discussions on Discord, GitHub, or HackMD that are relevant to the proposal. -## Features to be added +## Features to be added (if applicable) Give a description of what game mechanics you would like to add or change. This should be a general overview, with enough details on critical design points that someone can directly implement the feature from this design document. Exact numbers for game balance however are not necessary, as these can be adjusted later either during development or after it has been implemented, but mention *what* will have to be balanced and what needs to be considered when doing so. ## Game Design Rationale Consider addressing: -- How does the feature align with our [Core Design Principles](../space-station-14/core-design/design-principles.md) and game philosphy? +- How does the feature align with our [Core Design Principles](../space-station-14/core-design/design-principles.md) and game philosophy? - What makes this feature enjoyable or rewarding for players? - Does it introduce meaningful choices, risk vs. reward, or new strategies? - How does it enhance player cooperation, competition, or emergent gameplay? @@ -58,7 +63,7 @@ Consider addressing: - Could this feature increase the likelihood of griefing, rule-breaking, or player disputes? - How are the rules enforced mechanically by way the feature will be implemented? -# Technical Considerations +## Technical Considerations (if applicable) - Does the feature require new systems, UI elements, or refactors of existing ones? Give a short technical outline on how they will be implemented. - Are there any anticipated performance impacts? diff --git a/src/en/wizden-staff/maintainer/maintainer-workgroup-policy.md b/src/en/wizden-staff/maintainer/maintainer-workgroup-policy.md index d00dbc818c..8213113736 100644 --- a/src/en/wizden-staff/maintainer/maintainer-workgroup-policy.md +++ b/src/en/wizden-staff/maintainer/maintainer-workgroup-policy.md @@ -106,7 +106,6 @@ Conflicts on pull requests that are internal to the workgroup are subjected to t ### Design Documents Workgroups are encouraged to make design documents for their game area. -View the [Game Area Design Document Template](../../general-development/game-area-design-doc.md) and the Department Design Document Template on each drafted department for a good document basis. Relevant Game Area / Department design documents (which will describe pillars of design for the workgroup's dedicated area) should be merged before a workgroup will be considered fully-formed and functional. Merging such a document will signify that the maintainer team has agreed to give more freedom of action to the workgroup in the designated area, and therefore any merge must be approved by a majority of maintainer votes. The document must be accompanied by a separate Discourse thread, in which any other maintainer is able to request a merge delay (for a period not more than a week), in case they want to review the document but cannot do it right away.