Update 0002-split-content-directories-and-slug-handling.md

docs/decisions/0002-split-content-directories-and-slug-handling.md

@@ -1,26 +1,28 @@
-# 2. Split content directories and slug handling
+# 2. Split Content Directories and Slug Handling
 
 Date: 2024-09-30
 
 ## Context
 
-Splitting a Storyblok Space's content directories to support multiple site builds. This requires handling and refactoring of the current codebase to handle the change to where the content is store but also how links are build.
+We are restructuring a Storyblok Space to support multiple site builds by splitting the content directories. This change requires adjusting both how the content is stored and how links are generated. The main challenge is ensuring the content remains organized while maintaining a seamless user experience for content authors.
 
 ## Decision
 
-Slug sanitization handling and altering at the site code level was chosen as it strikes the best balance of effort and change for content authors. Introducing something like the Advanced Paths App for content authors would introduce another layer of complexity for them that they could be trained on but it is something that is easily lots and forgotten about in the Storyblok UI. By handling the prefix sanitization at the code and component layer we will be able to keep the content author user experience as similar to having just one site in the space as possible and keep the Storyblok application happy by having unique slugs and paths for everything.
+The solution we selected involves handling slug sanitization and modification at the site code level. This method was chosen because it strikes a balance between minimizing effort for developers and maintaining a simple workflow for content authors. Implementing something like the Advanced Paths App in Storyblok was considered, but it would add unnecessary complexity for authors. While the app could be useful, it risks being overlooked or forgotten in the UI, increasing the likelihood of confusion.
+
+By managing slug prefix sanitization at the code and component level, we ensure that authors can work with content in a way that feels as familiar as having a single site in the space. Meanwhile, the Storyblok application remains happy with unique slugs and paths, which is critical for ensuring proper functionality across multiple sites.
 
 ## Alternatives Considered
 
-1. **Storyblok's advanced paths app**  
-This was not chosen as the advanced paths did not solve the issue of two sites having the same slug. IE: multiple stories cannot have the same `contact` slug or `real_path` no matter where they are in the content directory.
+1. **Storyblok's Advanced Paths App**  
+   This option was rejected because it doesn’t resolve the issue of two sites sharing the same slug. For example, it’s not possible to have multiple stories with the same `contact` slug or `real_path`, regardless of their location in the content directory. Therefore, the Advanced Paths App wouldn't be a sufficient solution for the problem of duplicate slugs across different sites.
 
-2. **Netlify rewrites**  
-Create a proxy re-write that rewrites all slug prefixes to the clean url. This would not work on local and could be confusing. Still not a terrible option IMHO.
+2. **Netlify Rewrites**  
+   This approach involved using Netlify to create a proxy rewrite that would automatically adjust slug prefixes to create clean URLs. However, this method would not work in a local environment and could lead to confusion when debugging or handling different environments. While not a terrible option, it added unnecessary complexity.
 
-3. **Scoped API keys**  
-Does not solve the slug problem but does help with content fetching scope.
+3. **Scoped API Keys**  
+   Scoped API keys help with content-fetching limitations by defining access levels for specific content. However, they do not solve the slug duplication issue, making this approach irrelevant for the current challenge.
 
 ## Consequences
 
-Developers will have to be aware and savvy to the handling of the slugs. When fetching content from Storyblok they must use the full slug. When Creating pages or linking to paths they must strip the prefix from the url string. 
+Developers will need to be mindful of how slugs are handled in the codebase. When fetching content from Storyblok, the full slug (including the prefix) must be used. However, when creating pages or linking to specific paths, developers will need to strip the prefix from the URL string to ensure correct routing and navigation. This requires a level of attentiveness, but ensures that the system remains flexible and functional across multiple site builds.