readme-writer

Guidelines for writing module READMEs that explain how a module works to developers who need to use it or understand its internals. Use when documenting a module, package, or subsystem.

1. Umieść plik README w tym samym folderze co moduł, który dokumentujesz — nie w katalogu głównym projektu. Na przykład jeśli dokumentujesz moduł w src/sequencer/, umieść README w src/sequencer/README.md.

2. Zacznij od sekcji Overview — napisz 2–4 zdania wyjaśniające, co robi moduł i gdzie się wpisuje w system. Bądź konkretny: zamiast "obsługuje transakcje" napisz "wysyła transakcje L1, symuluje je, wybiera ceny gazu i monitoruje status".

3. Dodaj sekcję Usage Context, która wyjaśni, kiedy i jak moduł jest używany. Opisz, kto go wywołuje i w jakich warunkach. Jeśli moduł aktywuje się pod pewnymi warunkami, wymień je jako listę.

4. Dołącz przykład kodu pokazujący typowe użycie modułu. Jeśli to moduł narzędziowy, pokaż, jak go zaimportować i wywołać jego główne metody.

5. Zdefiniuj kluczowe pojęcia specyficzne dla domeny — bloki, checkpointy, sloty, propozycje lub inne terminy, które mogą być niejasne dla dewelopera czytającego kod.

6. Przejrzyj dokumentację pod kątem przejrzystości: każda sekcja powinna odpowiadać na pytanie dewelopera ("Co to robi?", "Kiedy go używam?", "Jak go używam?").