diff --git a/docs/dev/designs/index.rst b/docs/dev/designs/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..84993e1bd8fbfc1eb010d0fd8b33fee0e7da1103 --- /dev/null +++ b/docs/dev/designs/index.rst @@ -0,0 +1,7 @@ +System Designs +-------------- + +.. toctree:: + :maxdepth: 2 + + System Design Template <template> diff --git a/docs/dev/designs/template.rst b/docs/dev/designs/template.rst new file mode 100644 index 0000000000000000000000000000000000000000..8fbc2a587848b21069c43178ec71f65aed42998a --- /dev/null +++ b/docs/dev/designs/template.rst @@ -0,0 +1,95 @@ +$HEADLINE +========= + +*The goal is to do the least design we can get away with while still making a quality product.* +*Think of this as a tool to help define the problem, analyze solutions, and share results.* +*Feel free to skip sections that you don't think are relevant* +*(but say that you are doing so).* +*Delete the bits in italics* + +**Contacts:** *The primary contacts for this design.* +**Date:** *The last time this design was modified. YYYY-MM-DD* + +*Short description of the feature.* +*Consider clarifying by also describing what it is not.* + +Rationale +--------- + +*Why are we doing this now?* +*What value does this give to our users?* +*Which users?* + +User Stories +------------ + +**$STORY NAME** + +**Category:** *must / nice to have / must not* + +As a **$PERSON** I want **$FEATURE** so that **$BENEFIT**. + +**Acceptance Criteria:** + + * *What concrete conditions must be met for the implementation to be acceptable?* + * *Surface assumptions about the user story that may not be shared across the team.* + * *Describe failure modes and negative scenarios when preconditions for using the feature are not met.* + * *Place the story in a performance/scaling context with real numbers.* + +*Have as many as you like.* +*Group user stories together into meaningfully deliverable units.* + +*Gather Feedback* +----------------- + +*It might be a good idea to stop at this point & get feedback to make sure you're solving the right problem.* + +Alternatives Considered +----------------------- + +*What we've considered.* +*What trade-offs are involved with each choice.* +*Why we've chosen the one we did.* + +Detailed Implementation Design +------------------------------ + +*Focus on:* + +* external and internal interfaces +* how externally-triggered system events (e.g. sudden reboot; network congestion) will affect the system +* scalability and performance + +Data Integrity +~~~~~~~~~~~~~~ + +*If we get this wrong once, we lose forever.* +*What data does the system need to operate on?* +*How will old data be upgraded to meet the requirements of the design?* +*How will data be upgraded to future versions of the implementation?* + +Security +~~~~~~~~ + +*What threat model does this design take into account?* +*What new attack surfaces are added by this design?* +*What defenses are deployed with the implementation to keep those surfaces safe?* + +Backwards Compatibility +~~~~~~~~~~~~~~~~~~~~~~~ + +*What existing systems are impacted by these changes?* +*How does the design ensure they will continue to work?* + +Performance and Scalability +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*How will performance of the implementation be measured?* + +*After measuring it, record the results here.* + +Further Reading +--------------- + +*Links to related things.* +*Other designs, tickets, epics, mailing list threads, etc.* diff --git a/docs/index.rst b/docs/index.rst index eb6b59ec783b8aa6dfb3227ca51fe47e5f1b6bc7..c95dc5790e8bd4cd82560319cfb6e9d4f26720ae 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,13 +6,16 @@ Welcome to PrivateStorageio's documentation! ============================================ -Howdy! We separated the documentation into parts addressing different audiences. Please enjoy our docs for: +Howdy! +We separated the documentation into parts addressing different audiences. +Please enjoy our docs for: .. toctree:: :maxdepth: 2 Administrators <ops/README> Developers <dev/README> + System Designs <dev/designs/index> Naming