This is Part 3 (final instalment of the core arc). Start from Part 1 — Specification and Part 2 — Versioning, changelog & testing if you need context on the Slothy-style split between @slothy/core and @slothy/angular.
Parts 1 and 2 shaped the product and release discipline. Part 3 is about people: how others (or future you) can contribute safely and how you document the public surface so the library stays approachable.
Why contributor experience matters
A library without a clear entry for contributors will accumulate drive-by PRs, silent forks, or internal-only knowledge—all of which erode the contract you defined in Part 1.
Good contributor docs reduce friction for:
- External open source contributors.
- Other teams in your organization consuming
@slothy/*.
The goal is not bureaucracy; it is repeatable alignment with your architecture and versioning rules.
CONTRIBUTING.md — the onboarding README
Keep it short and actionable. Typical sections:
| Section | Purpose |
|---|---|
| Prerequisites | Node version, package manager (pnpm / npm), monorepo tool if any. |
| Clone & install | Exact commands (git clone, npm ci, npm run build). |
| Dev workflow | How to run tests, lint, and storybook/docs locally. |
| Project layout | Where domain lives vs adapters (@slothy/core vs @slothy/angular). |
| Pull requests | Branch naming, required checks, scope (one concern per PR). |
| Commits | Optional: Conventional Commits so changelog automation stays honest (Part 2). |
For internal libraries, mirror the same file in your internal wiki or doc portal, but keep the repo copy as the source of truth for anyone cloning the code.
Issue templates — classify before coding
Encourage reporters to choose bug vs feature vs question (or documentation).
A minimal bug template might ask:
- Package version (
@slothy/core/@slothy/angular). - Runtime (Node, browser, Angular version).
- Reproduction (StackBlitz, repo, or snippet).
- Expected vs actual behavior.
Feature requests should ask:
- What problem are you solving (user story), not only “add API X”.
This reduces back-and-forth and aligns with your MVP mindset from Part 1: not every idea should become scope.
RFCs for large or breaking changes
For changes that touch public API, multiple packages, or long-term behavior, use a lightweight RFC (Request for Comments):
- One short markdown file in
rfcs/or a GitHub Discussion: context, proposal, alternatives, impact (semver). - A time-boxed comment period (e.g. one week for org-internal, longer for popular OSS).
- Decision recorded in the RFC (accepted / superseded) and linked from the changelog when you ship.
This scales better than giant PRs as the only discussion venue.
Documentation — API surface as the product
TSDoc on public exports
Every exported symbol in @slothy/core should carry TSDoc (@param, @returns, @example where it helps). The example is often the fastest way to show intent—the same spirit as README-first in Part 1.
Generated API reference
Tools like TypeDoc (or API Extractor for stricter rollups) can turn TSDoc into a static site or a Markdown section you publish next to the README. You do not need a full documentation platform on day one; you need one place that lists exports and links to the README’s narratives.
“Guides” vs “API”
- Guides (tutorials, migration guides): human-written, versioned with the repo.
- API reference: generated from types, regenerated in CI on release.
Keep navigation obvious: “Getting started” → “Configuration” → “Angular adapter” → “API”.
Security and conduct (briefly)
SECURITY.md: how to report vulnerabilities (email, GitHub Security Advisories). Do not rely only on public issues for sensitive reports.CODE_OF_CONDUCT: for open source communities, adopt a standard (Contributor Covenant) and enforce it consistently.
Internal org libraries still benefit from a clear security contact and dependency update policy (Dependabot).
How Part 3 closes the series
| Part | Focus |
|---|---|
| 1 — Specification | What to build and how to package it |
| 2 — Versioning & testing | How the contract evolves and stays verified |
| 3 — Contributors & docs | How people align with that contract and find the right abstractions |
Final thought
Libraries are social objects: they exist at the intersection of code, documentation, and expectations. Investing in the same rigor for contributors and docs as for API design is what keeps a package like Slothy usable years after the first line of code.
Tags: open source, library, TypeScript, Angular, documentation, contributing