Update also docs introduction and overview to align.

Author: runemalm

docs/index.rst

@@ -6,21 +6,25 @@
 py-dependency-injection
 =======================
 
-A dependency injection library for Python.
+A dependency injection library for Python — inspired by the built-in DI system in ASP.NET Core.
 
-Purpose
--------
+Overview
+--------
 
-Dependency injection is a powerful design pattern that promotes loose coupling and enhances testability in software applications. `py-dependency-injection` is a prototypical implementation of this pattern, designed to provide the essential features needed for effective dependency management in both small scripts and larger software projects.
+`py-dependency-injection` provides a lightweight and extensible way to manage dependencies in Python applications. It promotes constructor injection, supports scoped lifetimes, and encourages clean architecture through explicit configuration and testable design.
 
-This library is particularly suited for beginners exploring the concept of dependency injection, as it offers a straightforward and easy-to-understand implementation. It serves as an excellent starting point for learning the pattern and can also be used as a foundational base for frameworks requiring a more specialized interface for dependency injection.
+This library is well-suited for both standalone use in Python applications and as a foundation for frameworks or tools that require structured dependency management.
 
 Key Advantages
 --------------
 
-- **Suitable for Learning:** Ideal for beginners exploring the concept of dependency injection.
-- **Base Implementation for Frameworks:** Can be used as a foundational base for frameworks requiring a more specialized interface for dependency injection.
-- **Standalone Solution:** Can also be used on its own, as a fully-featured dependency injection solution in any software project.
+- **Familiar model** – Inspired by ASP.NET Core’s DI system
+- **Scoped lifetimes** – Support for `singleton`, `scoped`, and `transient` registrations
+- **Explicit injection** – Promotes clarity over magic
+- **Test-friendly** – Designed for container isolation and overrides
+- **Minimalistic** – Easy to use, extend, and integrate
+
+You can find the source code for `py-dependency-injection` in our `GitHub repository <https://github.com/runemalm/py-dependency-injection>`_.
 
 .. userguide-docs:
 .. toctree::

docs/userguide.rst

@@ -9,9 +9,9 @@ Getting Started
 Introduction
 ############
 
-`py-dependency-injection` is a lightweight and flexible dependency injection library for Python. It simplifies managing dependencies in your applications, promoting cleaner and more testable code.
+`py-dependency-injection` is a lightweight and extensible dependency injection library for Python — inspired by the built-in DI system in **ASP.NET Core**. It promotes constructor injection, supports scoped lifetimes, and encourages clean, testable application architecture.
 
-This guide will help you understand the key concepts and how to start using the library. For detailed examples, see the `Examples` section.
+This guide provides an overview of the key concepts and demonstrates how to start using the library effectively. For detailed examples, see the `Examples` section.
 
 ############
 Installation
@@ -75,11 +75,11 @@ Basic workflow:
 Best Practices
 ##############
 
-- **Use Constructor Injection**: Preferred for most cases as it promotes clear and testable designs.
-- **Leverage Tags for Organization**: Group dependencies logically using tags.
-- **Choose the Right Scope**: Use scoped or singleton lifetimes to optimize performance and resource usage.
-- **Keep Dependencies Decoupled**: Avoid tightly coupling your components to the container.
-- **Isolate Contexts with Containers**: Use multiple containers to manage dependencies for separate modules or contexts.
+- **Prefer Constructor Injection**: It promotes clear interfaces and testable components.
+- **Use the Right Lifetime**: Choose between transient, scoped, and singleton based on your component's role.
+- **Organize with Tags**: Use tag-based registration and resolution to group related services.
+- **Avoid Container Coupling**: Inject dependencies via constructors rather than accessing the container directly.
+- **Use Multiple Containers When Needed**: For modular apps or test isolation, create dedicated containers.
 
 #################
 Where to Go Next?