From 8264c34e0155949964a33ffa05b6a66c187f4234 Mon Sep 17 00:00:00 2001 From: TemporalOroboros Date: Wed, 27 Sep 2023 17:17:57 -0700 Subject: [PATCH] Section for feature/rework proposal design docs. (#35) Co-authored-by: Kara --- src/SUMMARY.md | 10 +++- .../codebase-info/pull-request-guidelines.md | 1 + src/en/general-development/tips/decorum.md | 14 ++++++ .../tips/design-principles.md | 33 +++++++++++++ .../tips/proposal-guidelines.md | 46 +++++++++++++++++++ src/en/templates/proposal.md | 3 ++ 6 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 src/en/general-development/tips/decorum.md create mode 100644 src/en/general-development/tips/design-principles.md create mode 100644 src/en/general-development/tips/proposal-guidelines.md create mode 100644 src/en/templates/proposal.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 0f4f6c392..2d524c251 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -34,6 +34,9 @@ General Development - [Writing Guidebook Entries](en/general-development/tips/writing-guidebook-entries.md) - [Config File Reference](en/general-development/tips/config-file-reference.md) - [YAML Crash Course](en/general-development/tips/yaml-crash-course.md) + - [Feature Proposals](en/general-development/tips/proposal-guidelines.md) + - [Expected Team Decorum & Usage](en/general-development/tips/decorum.md) + - [Fundamental Design Principles](en/general-development/tips/design-principles.md) SS14 By Example @@ -111,6 +114,11 @@ Space Station 14 - [Dungeons](en/space-station-14/dungeons.md) - [NPCs](en/space-station-14/npcs.md) +Design Proposals +================ + +---------------------- + Server Hosting ============== @@ -158,4 +166,4 @@ Community - [Admin Tooling](en/community/admin/admin-tooling.md) - [Admin Command Cookbook](en/community/admin/admin-tooling/admin-command-cookbook.md) - [Wizards Den Admin Policy](en/community/admin/wizards-den-admin-policy.md) - - [Wizards Den Banning Policy](en/community/admin/wizards-den-banning-policy.md) \ No newline at end of file + - [Wizards Den Banning Policy](en/community/admin/wizards-den-banning-policy.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 9db8234dc..55f591627 100644 --- a/src/en/general-development/codebase-info/pull-request-guidelines.md +++ b/src/en/general-development/codebase-info/pull-request-guidelines.md @@ -13,6 +13,7 @@ Following these guidelines will make contributing much easier, and will help you - If you move a file to a different folder and/or namespace, put that in its own commit when possible to make it easier to tell what got changed in a file and what was just moved. - 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. - Try to split your PR into smaller ones where it makes sense to do so. This makes it significantly easier to read and can lead to faster reviews. It's also usually easier for you, and means you will receive earlier feedback and can avoid spending time making changes that have to be reworked. +- 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](../tips/proposal-guidelines.md) before you start working on actually implementing it. - Avoid force-pushing to your branch. This makes all reviews show as 'outdated', even if they have not been addressed yet, which makes it much harder for us. - When you're addressing reviews, click 'Resolve conversation' on GitHub once your revised code has been pushed. - If you have questions about reviews that were submitted on your PR (or code questions in general, of course), feel free to ask for clarification on GitHub or Discord in #howdoicode. diff --git a/src/en/general-development/tips/decorum.md b/src/en/general-development/tips/decorum.md new file mode 100644 index 000000000..cb250c5ab --- /dev/null +++ b/src/en/general-development/tips/decorum.md @@ -0,0 +1,14 @@ +Expected Team Decorum & Usage +============================= + +- 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. +- Documents should note if a maintainer has approved it or not in the title in brackets along with the name if one exists. i.e. [mirrorcult, Approved] or [mirrorcult, Unapproved] +- 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 posted: + +- Should conform to the basic [SS14 Game Design Principles](./design-principles.md) as well as this document obviously. +- Should contain sufficient justification for their existence, +- Can be removed by consensus or at admin discretion. +- Are a reflection of SS14 to others that may be interested in how the game is designed. Take note of that. diff --git a/src/en/general-development/tips/design-principles.md b/src/en/general-development/tips/design-principles.md new file mode 100644 index 000000000..bae1badcb --- /dev/null +++ b/src/en/general-development/tips/design-principles.md @@ -0,0 +1,33 @@ +# SS14 Fundamental Design Principles + +The purpose of this document is to outline the basics of how Space Station 14 upstream design is approached, taking into consideration its status as a greenfield project and taking care to build a foundation for the future fork ecosystem. + +## Social Gameplay + +Mechanics should seek to be pro-social and encourage interacting with other players. These interactions need not be strictly cooperative or competitive in nature. Humans are chaotic by nature, and provide depth and replayability to games that cannot fully be achieved through programmed mechanics alone. Thus, we should utilize that power to drive gameplay. + +Mechanics which incentivize players to do them entirely alone, or mechanics which would be just as fun and fulfilling if done on a private test server with only one player, **will not be added to SS14**. + +These mechanics detract from the overall game by segmenting players into their own separate regions of play. Mechanics which are "simpler" but reward social gameplay will always be preferred to mechanics which are "deep" but are single-player. + +Parts of a whole gameplay loop or mechanic may be achievable by a single player. It's obviously not feasible to have everything forcibly involve multiple people, but care should be taken to try and incentivize social gameplay above singleplayer gameplay, even if something *can* be completed solo. + +An addendum to this principle is that, if a mechanic involves perceived NPCs or AI mobs, you should always try to find ways to put real humans in their place. For example, offering ghost roles to hostile mobs, or crafting an economy system that is player-motivated rather than externally-motivated. + +Negative examples of this principle in Space Station 13: + +- Lavaland mining +- Virology + +Positive examples of this principle in Space Station 14: + +- Diseases +- Salvage + +## Intuitive Simulation + +Space Station 13/14 + +## Discoverable Interactions + +## Systems-based Design diff --git a/src/en/general-development/tips/proposal-guidelines.md b/src/en/general-development/tips/proposal-guidelines.md new file mode 100644 index 000000000..9f300aeb9 --- /dev/null +++ b/src/en/general-development/tips/proposal-guidelines.md @@ -0,0 +1,46 @@ +# So you want to X where X is large + +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? + +Just follow [our guide](../../meta/guide-to-editing-docs.md) on editing any part of this site and PR your proposal as a page under the "Design Proposals" section found in the sidebar between "Space Station 14" and "Server Hosting". + +Proposals that get approved by a maintainer will be merged to this site, which is basically the green light for you or someone else to go ahead and implement it. + +``` 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 entirity 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 entirity 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 Fundamental Design Principles](./design-principles.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](./decorum.md). +``` diff --git a/src/en/templates/proposal.md b/src/en/templates/proposal.md new file mode 100644 index 000000000..7f13ef5ae --- /dev/null +++ b/src/en/templates/proposal.md @@ -0,0 +1,3 @@ +```admonish info "Proposal" +This page is a proposed feature or rework that hasn't been implemented yet. +``` \ No newline at end of file