Merge branch 'dev-readme'

Author: Exadra37

README.md

@@ -1,36 +1,74 @@
 # 🪶 Elixir Scribe 📜
 
-Scribes were elites in ancient societies, highly regarded and holding special social status. They were disciplined and known for their excellent craftsmanship in writing laws, copying documents, and other related tasks.
+Scribes were an elite in ancient societies, highly regarded and holding special social status. They were disciplined and known for their excellent craftsmanship in writing laws, copying documents, and other related tasks.
 
-For developers, the Scribe tool aims to help them embody the values of discipline and craftsmanship of the Scribes, enabling them to more easily write clean code in a clean software architecture for enhanced developer experience and productivity.
+The motivation to create the Scribe tool was to encourage developers to write cleaner code in a more organized software architecture, enabling them to know in seconds all domains (contexts), resources, and actions used in a project, while reducing complexity. This reduction in complexity translates into fewer bugs and makes it easier to add new features and implement bug fixes when they arise. Consequently, this results in less maintenance and technical debt across the lifetime of a project, leading to a more robust and easier-to-work-with codebase. Ultimately, this enhances developer experience, velocity and productivity. This is a win win for both the business and developers.
 
-For businesses, the Scribe tool aims to increase velocity by enhancing developers' productivity, reducing technical debt and bugs in the codebase, while allowing features to be added more seamlessly.
+The Scribe tool enables developers craftsmanship and professionalism to reach new levels never imagined before or thought to not be easy to achieve.
 
-Both businesses and developers will find that these benefits are visible in the short and long term, but they will appreciate them even more as more features are added and fewer bugs arise due to the overall reduced complexity when compared with less well-structured approaches. This translates into less maintenance and a more robust and easier-to-work-with codebase.
+Don't just be a Developer or Engineer, become a Scribe Developer and Engineer 🚀
 
-Some of the benefits of using the Scribe tool to start and maintain an Elixir or Phoenix project:
 
-* Know all domains (contexts), resources, and actions used in your project by just looking at the folder structure.
-* Newcomers to the project or anyone returning after a while can easily understand what the project is all about and quickly start working on new features or bugs (folder structure for the win).
-* The single responsibility principle is encouraged by the design of the folder structure, where a clear separation of domains, resources, and actions occurs, encouraging one resource action per module.
-* Helps reduce tech debt due to the separation of concerns encouraged by the folder structure.
-* It's much easier to find where to add a new feature without mixing it with existing code. For example: If it's a new action on a resource, just add one more action folder and the respective module(s) inside it.
-* Quickly find and start debugging a bug because actions aren't entangled in a huge module with several resources for a domain (context). For example, if the bug is about creating a resource on a given domain, it's straightforward to know where to start due to the folder structure.
-* The folder structure is documentation that never lies about what domains (contexts), resources, and actions are available in your project, whether huge or small.
+## Folder Structure
 
-The Scribe tool enables developers craftsmanship and professionalism to reach new levels never imagined before or thought to not be easy to achieve.
+Can you grasp, in seconds, all domains, resources, and actions in your current large professional or pet projects?
 
-Don't just be a Developer or Engineer, become a Scribe Developer and Engineer 🚀
+With the Elixir Scribe folder structure you will always reply **YES** to the above question.
 
+```
+lib/acme_shop
+├── catalog
+│   ├── category
+│   │   ├── assign
+│   │   ├── change
+│   │   ├── create
+│   │   ├── delete
+│   │   ├── get
+│   │   ├── list
+│   │   └── update
+│   └── product
+│       ├── assign
+│       ├── change
+│       ├── create
+│       ├── delete
+│       ├── get
+│       ├── list
+│       └── update
+└── warehouse
+    └── inventory
+        ├── assign
+        ├── change
+        ├── create
+        ├── delete
+        ├── get
+        ├── list
+        └── update
+```
 
-## Contributing
+> Domains: catalog, warehouse - Resources: category, product, inventory - Actions: assign, change, ...
+
+This is a very simplistic view of a project. Now, imagine reaping the benefits of this folder structure implemented on your extensive codebase, which may now contain dozens, hundreds, or even thousands of resources, each with potentially more actions than the ones exemplified here.
+
+Take a moment to compare and contemplate this folder structure with the traditional one used in an Elixir or Phoenix project, which often condenses several resources and all their actions into a single module (the context). Alternatively, in cases where contexts are not used, they may simply consist of large modules with only one resource and all its actions.
+
+Can you now understand why Elixir Scribe encourages developers to write cleaner code in a more organized software architecture?
 
-The Elixir Scribe tool is highly opinionated, therefore I ask you to first [open a discussion](https://github.com/Exadra37/elixir-scribe/discussions/new?category=ideas) to propose your idea to avoid working and then seeing the PR refused.
+
+## Benefits of Using the Elixir Scribe Tool to Create and Maintain Elixir and Phoenix Projects
+
+* Know in seconds all domains (contexts), resources, and actions used in your project by just looking at the folder structure. This is priceless for anyone working on the project.
+* Newcomers to the project or anyone returning after a while can easily understand what the project is all about and quickly start working on new features or bugs (folder structure for the win).
+* The single responsibility principle is encouraged by the design of the folder structure, where a clear separation of domains, resources, and actions occurs, encouraging one resource action per module.
+* Helps to reduce tech debt due to the separation of concerns encouraged by the folder structure, which naturally guides developers to not mix new features into an existing module, whether it's a new domain, resource, or just an action on a resource.
+* It's much easier to find where to add a new feature without mixing it with existing code. For example: If it's a new action on a resource, just add one more action folder and the respective module(s) inside it.
+* Quickly find and start debugging a bug because actions aren't entangled in a huge module with several resources for a domain (context). For example, if the bug is about creating a resource on a given domain, it's straightforward to know where to start due to the folder structure.
+* Each resource on a domain has a public API to avoid direct access to the underlying implementation of each resource. This removes cross-domain boundary calls into the internals of each resource implementation, preventing the coupling of domains, which is a significant source of technical debt and complexity in a codebase. The Resource public API MUST be used not only from other domains but also from within the domain itself. This will allow the internals of a resource in a domain to change as needed, provided that we do not affect the public API for it.
+* The folder structure is documentation that never lies about what domains (contexts), resources, and actions are available in your project, whether huge or small.
 
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
+The [Elixir Scribe](https://hexdocs.pm/elixir_scribe/api-reference.html) package can be installed
 by adding `elixir_scribe` to your list of dependencies in `mix.exs`:
 
 ```elixir
@@ -41,6 +79,15 @@ def deps do
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at <https://hexdocs.pm/elixir_scribe>.
+
+## Documentation
+
+The docs can be found at <https://hexdocs.pm/elixir_scribe>.
+
+Documentation is generated with [ExDoc](https://github.com/elixir-lang/ex_doc).
+
+
+## Contributing
+
+The Elixir Scribe tool is highly opinionated, therefore I ask you to first [open a discussion](https://github.com/Exadra37/elixir-scribe/discussions/new?category=ideas) to propose your idea to avoid working and then seeing the PR refused.
+

mix.exs

@@ -49,6 +49,7 @@ defmodule ElixirScribe.MixProject do
     [
       # {:dep_from_hexpm, "~> 0.3.0"},
       # {:dep_from_git, git: "https://github.com/elixir-lang/my_dep.git", tag: "0.1.0"}
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}
     ]
   end
 end

mix.lock

@@ -0,0 +1,8 @@
+%{
+  "earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"},
+  "ex_doc": {:hex, :ex_doc, "0.32.2", "f60bbeb6ccbe75d005763e2a328e6f05e0624232f2393bc693611c2d3ae9fa0e", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "a4480305cdfe7fdfcbb77d1092c76161626d9a7aa4fb698aee745996e34602df"},
+  "makeup": {:hex, :makeup, "1.1.2", "9ba8837913bdf757787e71c1581c21f9d2455f4dd04cfca785c70bbfff1a76a3", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cce1566b81fbcbd21eca8ffe808f33b221f9eee2cbc7a1706fc3da9ff18e6cac"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
+  "makeup_erlang": {:hex, :makeup_erlang, "1.0.0", "6f0eff9c9c489f26b69b61440bf1b238d95badae49adac77973cbacae87e3c2e", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "ea7a9307de9d1548d2a72d299058d1fd2339e3d398560a0e46c27dab4891e4d2"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
+}