Summary
The cardano-api README.md currently provides only a brief high-level description, a contributing link, a core-maintainers list, and links to external documentation. For a Core Cardano repository, this leaves new contributors and library consumers without a clear on-ramp. This issue tracks the documentation gaps and proposes concrete improvements.
Raised as part of a Developer Experience Working Group documentation review.
Observed gaps
1. Missing or unclear project overview
The overview section describes the repo only as an integration of the ledger, consensus, and networking repositories. It does not explain what cardano-api is from a consumer's perspective — what it enables, who should use it, and how it fits into the wider stack (e.g. its relationship to cardano-node and cardano-cli).
2. No clear quick start guide
There is no "Quick Start" / "Getting Started" section. A reader has no guided first step — how to add the library as a dependency, build it, or run a minimal example.
3. Setup instructions are incomplete or scattered
The README contains no build instructions. A newcomer has to infer the workflow from cabal.project and flake.nix. Building a Haskell + Nix project is non-trivial and should be documented explicitly, covering both the Cabal path and the Nix path.
4. Lack of code examples
There are no usage examples in the README. At minimum, a small, copy-pasteable example would help consumers evaluate and adopt the library, with a link to fuller examples or the Haddock docs.
5. No clear explanation of dependencies or requirements
Required toolchain versions are not stated — GHC version, Cabal version, Nix (and whether flakes are required), and any system-level dependencies. Consumers currently discover these by trial and error.
6. Outdated sections (to verify)
The Documentation section links to the Cardano Node Wiki under the input-output-hk org. Please verify these links are still the canonical, current location, and relink or annotate if anything has moved.
Proposed improvements
Restructure README.md to include, in order:
- Overview : what the library does, who it is for, and where it sits in the Cardano stack
- Requirements : GHC / Cabal / Nix versions and any system prerequisites
- Quick start : the shortest path to building and running a minimal example
- Setup / build : full build instructions for both Cabal and Nix
- Usage examples : at least one minimal, runnable example, linking out to more
- Documentation : Haddock and wiki links, verified as current
- Contributing : keep the existing link
Summary
The
cardano-apiREADME.mdcurrently provides only a brief high-level description, a contributing link, a core-maintainers list, and links to external documentation. For a Core Cardano repository, this leaves new contributors and library consumers without a clear on-ramp. This issue tracks the documentation gaps and proposes concrete improvements.Raised as part of a Developer Experience Working Group documentation review.
Observed gaps
1. Missing or unclear project overview
The overview section describes the repo only as an integration of the ledger, consensus, and networking repositories. It does not explain what
cardano-apiis from a consumer's perspective — what it enables, who should use it, and how it fits into the wider stack (e.g. its relationship tocardano-nodeandcardano-cli).2. No clear quick start guide
There is no "Quick Start" / "Getting Started" section. A reader has no guided first step — how to add the library as a dependency, build it, or run a minimal example.
3. Setup instructions are incomplete or scattered
The README contains no build instructions. A newcomer has to infer the workflow from
cabal.projectandflake.nix. Building a Haskell + Nix project is non-trivial and should be documented explicitly, covering both the Cabal path and the Nix path.4. Lack of code examples
There are no usage examples in the README. At minimum, a small, copy-pasteable example would help consumers evaluate and adopt the library, with a link to fuller examples or the Haddock docs.
5. No clear explanation of dependencies or requirements
Required toolchain versions are not stated — GHC version, Cabal version, Nix (and whether flakes are required), and any system-level dependencies. Consumers currently discover these by trial and error.
6. Outdated sections (to verify)
The Documentation section links to the Cardano Node Wiki under the
input-output-hkorg. Please verify these links are still the canonical, current location, and relink or annotate if anything has moved.Proposed improvements
Restructure
README.mdto include, in order: