doc: Tweak

README.md

@@ -3,26 +3,7 @@
 Pyproject.nix is a collection of Nix utilities to work with Python project metadata in Nix.
 It mainly targets [PEP-621](https://peps.python.org/pep-0621/) compliant `pyproject.toml` files and data formats, but also implement support for legacy formats such as `requirements.txt`.
 
-Pyproject.nix aims to be a swiss army knife of unopinionated utilities to build opinionated higher level & more opinionated tooling on top off.
-
-Pyproject.nix is currently in use in [poetry2nix](https://github.com/nix-community/poetry2nix) & [dream2nix](https://github.com/nix-community/dream2nix).
-
-### Design goals
-
-- Provide low level plumbing that is useful in other projects like [poetry2nix](https://github.com/nix-community/poetry2nix) & [dream2nix](https://github.com/nix-community/dream2nix).
-
-- Suport for many package managers
-
-### Roadmap
-
-- Python metadata support
-  - [x] [PEP 427](https://peps.python.org/pep-0427/) – The Wheel Binary Package Format 1.0
-  - [x] [PEP 440](https://peps.python.org/pep-0440/) – Version Identification and Dependency Specification
-  - [x] [PEP 508](https://peps.python.org/pep-0508/) – Dependency specification for Python Software Packages
-  - [x] [PEP 518](https://peps.python.org/pep-0518/) – Specifying Minimum Build System Requirements for Python Projects
-  - [x] [PEP 599](https://peps.python.org/pep-0599/) – The manylinux2014 Platform Tag
-  - [x] [PEP 600](https://peps.python.org/pep-0600/) - Future ‘manylinux’ Platform Tags for Portable Linux Built Distributions
-  - [x] [PEP 621](https://peps.python.org/pep-0621/) - Storing project metadata in pyproject.toml
+Pyproject.nix aims to be a swiss army knife of simple customizable utilities that supports many use cases.
 
 ### Matrix chat
 

doc/src/introduction.md

@@ -1,11 +1,18 @@
 # Introduction
 
+## What is pyproject.nix
+
+Pyproject.nix is a collection of Nix utilities to work with Python project metadata in [Nix](https://nixos.org/).
+It mainly targets [PEP-621](https://peps.python.org/pep-0621/) compliant `pyproject.toml` files and data formats, but also implement support for other & legacy formats such as [Poetry](https://python-poetry.org/) & `requirements.txt`.
+
+Pyproject.nix aims to be a swiss army knife of simple customizable utilities that works together with the [nixpkgs Python infrastructure](https://nixos.org/manual/nixpkgs/stable/#python).
+
 ## Foreword
 
 This documentation only helps you to get started with `pyproject.nix`.
 As it's a toolkit with many use cases not every use case can be documented fully.
 
-This documentation is centered around packaging Python applications.
+This documentation is centered around packaging Python applications & managing development environments.
 For other use cases see the reference documentation.
 
 ## Concepts
@@ -15,7 +22,7 @@ The best way to get started is to understand these concepts and how they fit tog
 
 ### [Project](./lib/project.md)
 
-A `project` attrset is a high-level representation of a project that includes:
+A `project` attribute set is a high-level representation of a project that includes:
 
 - The parsed `pyproject.toml` file
 - Parsed dependencies

templates/pyproject/flake.nix

@@ -20,7 +20,8 @@
       # This example is only using x86_64-linux
       pkgs = nixpkgs.legacyPackages.x86_64-linux;
 
-      # We are using the default Python3 interpreter & package set.
+      # We are using the default nixpkgs Python3 interpreter & package set.
+      #
       # This means that you are purposefully ignoring:
       # - Version bounds
       # - Dependency sources (meaning local path dependencies won't resolve to the local path)