Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

technical-documentation-engineering

/technical-documentation-engineering

Opisuje praktykę utrzymywania README, krótkich zapisów decyzji i dokumentów zmienianych w tym samym PR co kod.

Licencja
Apache-2.0
Ostatnia zmiana repozytorium
02.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 02.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Opisuje praktykę utrzymywania README, krótkich zapisów decyzji i dokumentów zmienianych w tym samym PR co kod.

Oryginalny opis (EN)

Engineering practice: Technical documentation — Keep a working README, short decision records and docs that change in the same pull request as the code, so people and agents can trust what they read. Use in any language or framework whenever this practice applies, and when reviewing work that should follow it.

Jak działa

  1. How to do it
  2. Checklist
  3. Rules
  4. Do
  5. Don't
  6. Quality gates
  7. Workflow
  8. Examples
  9. Further reading
Sekcje z nagłówków SKILL.md, w oryginale · 85 linii, 766 słów
Podgląd SKILL.md
---
name: technical-documentation-engineering
description: "Engineering practice: Technical documentation — Keep a working README, short decision records and docs that change in the same pull request as the code, so people and agents can trust what they read. Use in any language or framework whenever this practice applies, and when reviewing work that should follow it."
type: engineering
stack: practice
core: "1.0"
checked: 2026-10-26
---

# Technical documentation

Keep a working README, short decision records and docs that change in the same pull request as the code, so people and agents can trust what they read.

Use this for any repository others will run, change or depend on. Docs that live beside the code and are updated with it prevent stale setup steps, forgotten reasons for past decisions and onboarding that depends on asking the one person who knows.

## How to do it
1. **Write a README that runs** — Cover what the project is in two sentences, prerequisites with versions, install, run, test and deploy commands, and where to get help. Follow it on a clean machine or container to prove it works.
2. **Record decisions as ADRs** — For each significant technical choice, add a numbered decision record with context, the decision, alternatives considered and consequences. Never edit an accepted record; supersede it with a new one.
3. **Document the architecture briefly** — Keep one page with a simple diagram of the main components, data flow and external dependencies. Link to code entry points rather than describing them in prose.
4. **Explain why in code, not what** — Use comments for intent, constraints and non-obvious trade-offs. Document public functions and APIs with their inputs, outputs and errors.
5. **Update docs with the change** — When a pull request changes setup, configuration, an API or behaviour, update the related docs in that same pull request.
6. **Write for the task** — Organise guides around what the reader is trying to do. Use numbered steps, copyable commands and expected output.
7. **Check docs automatically** — Lint Markdown, check links in CI, and run code samples or commands where practical so broken docs fail the build.

## Checklist
- [ ] README install, run and test steps work on a clean environment
- [ ] Significant decisions in this change have an ADR
- [ ] Docs affected by the change are updated in the same pull request
- [ ] Public APIs list inputs, outputs and errors
- [ ] All links in docs resolve
- [ ] Changelog has an entry for user-visible changes

## Rules
- Store docs in the repository next to the code they describe. _(Docs reviewed with the code stay accurate; docs in a separate tool drift.)_
- Never put real credentials, internal hostnames or personal data in docs or examples; use placeholders and environment variable names. _(Docs are copied, shared and indexed widely.)_
- Delete docs that are wrong rather than leaving them with a warning. _(Wrong docs cost more time than missing docs.)_
- Give every diagram a text description and use real headings in order. _(Readers using assistive technology need the same information.)_

## Do
- Keep a CONTRIBUTING file with branch, test and review expectations
- Date ADRs and give each a status: proposed, accepted or superseded
- Write docs a coding agent can follow: exact commands and file paths

## Don't
- Do not describe line by line what the code already says
- Do not leave TODO sections in published docs
- Do not merge behaviour changes without updating the docs they invalidate

## Quality gates
| Gate | Tool | Threshold | When |
|---|---|---|---|
| Docs checks | Markdown linter + link checker in CI | 0 lint errors; 0 broken links | Every pull request touching docs |

## Workflow
**Review**
- Ask whether the change invalidates any README step, API doc or ADR

**Definition of done**
- Docs and changelog updated in the same pull request as the behaviour change

## Examples
### Decision record template (`docs/adr/0007-use-postgres-for-jobs.md`)

```markdown
# 7. Use the main Postgres database for background jobs

Date: 2026-10-26
Status: accepted

## Context
We need retries and scheduling for about 2,000 jobs a day. Running a
separate queue service adds another system to operate and monitor.

## Decision
Store jobs in a dedicated table in the existing database and process
them with row-level locking.

## Alternatives considered
- Dedicated message broker: more throughput than we need, more ops.
- In-process timers: lost on restart.

## Consequences
- One less service to run.
- Revisit if volume passes 100,000 jobs a day (see ADR 3 for limits).
```

## Further reading
- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) — A simple, readable format for recording user-visible changes.
- [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) — Engineering skills for coding agents that include documentation and decision-record workflows.
- [anthropics/skills](https://github.com/anthropics/skills) — Shows how instructions are written so agents can follow them, a useful model for agent-readable docs.

_Written for Celestial; the sources above inspired it._
Pliki w paczce (4)
  • AGENTS.md 3 KB
  • README.md 2 KB
  • SKILL.md 5 KB
  • rules/technical-documentation-engineering.mdc 3 KB

Wersje

W bazie nie ma innych skilli o nazwie technical-documentation-engineering.

Migawka bazy z 13.11.2026 · wersja paczki fce0537976a1 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100code-review-engineering
    Opisuje praktykę przeglądu kodu w stałej kolejności, od poprawności po testy, tak by uwagi były konkretne i wykonalne.
  • 100design-tokens-to-code-engineering
    Opisuje praktykę: tokeny projektowe w kodzie, z jednego źródła tokenów generowany kod platform i testy wizualne, by zmiana marki była jednym commitem.
  • 100documentation-engineer
    Pisze przejrzystą dokumentację techniczną, tworzy README i dokumentuje kod na prośbę użytkownika.
  • 100documentation-engineer
    Tworzy czytelną dokumentację techniczną, na przykład README i opisy kodu, gdy użytkownik prosi o napisanie dokumentów.
  • 100code-documentation
    Analizuje repozytorium i tworzy lub aktualizuje README, dokumentację API i architektury, a potem ją sprawdza.
  • 100readme-generator
    Prawdopodobnie generuje pliki README w ramach umiejętności z obszaru dokumentacji technicznej.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.