readme.md

W projektach własnych tematów WordPress o ile nie korzystasz z repozytorium GIT warto dodać plik .md jako dokumentację theme.
Może to być standardowe README.md, lub CHANGELOG.md jeśli projekt jest długoterminowy lub DEV-NOTES.md do zapisania istotnych lub nieoczywistych informacji.

README – co to jest i jak tego używać – dokumentacja użytkowa
DEV-NOTES – jak to działa w środku i dlaczego jest zrobione właśnie tak – dokumentacja architektoniczna
CHANGELOG – historia zmian

poniższy opis jest sugestią, wszystko zależy od projektu i teamu z jakim pracujesz.

README.md

Cel

Onboarding i szybkie zrozumienie projektu. Dla:

• nowy developer
• PM
• ktoś wdrażający projekt
• ty za pół roku 😉

Zawiera

• opis projektu
• wymagania (WP, PHP, ACF)
• strukturę plików
• ogólne informacje o zmianach
• instrukcję wdrożenia

Charakter

• uporządkowany
• dość ogólny
• bez wchodzenia w głębokie technikalia

DEV-NOTES.md

Cel

Wyjaśnia decyzje architektoniczne i nietypowe rozwiązania. Dla:

• developer, który będzie coś zmieniał
• osoby debugującej problem
• osoby robiącej refactor

Zawiera

przykładowo:

• dlaczego query jest zrobione przez _wp_page_template
• czemu nie używamy standardowej pętli
• dlaczego jest custom hook zamiast template hierarchy
• edge case’y
• znane problemy
• rzeczy „nie ruszać bez analizy”

Charakter

• bardziej techniczny
• mniej „ładny”
• bardziej jak notatnik architekta