Powinien on zawierać wszystkie aspekty, które deweloper musi znać, a których nie można uzyskać bezpośrednio od dewelopera. kod. Obejmują one instrukcje programowania, pełne instrukcje wdrażania, opisy integracji zewnętrznej i tak dalej. Ten post poprowadzi Cię przez proces tworzenia potężnego, pięknego i czytelnego pliku README dla Twojej aplikacji. projekt.

Dobry wstęp do dobrze przygotowanej dokumentacji projektu można znaleźć w przewodnikach github: https://guides.github.com/features/wikis/. Stanowi to, że "README powinno zawierać tylko niezbędne informacje dla programistów, aby mogli zacząć korzystać z projektu i wnosić do niego swój wkład".

Mając to na uwadze, przedstawimy listę komponentów i najlepszych praktyk, które stosujemy w Codest przy tworzeniu dokumentacji projektowej.

Szybkie wprowadzenie

- Tytuł projektuJest to obowiązkowy element każdego README.

- Odznaki statusuJeśli korzystasz z zewnętrznych pomiarów jakości kodu, zautomatyzowanych testów lub innych narzędzi, początek dokumentu jest dobrym miejscem, aby pokazać innym, czy działają.

- OpisDołącz kilka zdań na temat projektu, aby szybko opisać jego główny cel i działanie.

Spis treści

Lista zawartości może być przydatna w przypadku długich plików dokumentacji, ale jeśli README jest dość zwięzłe, nie jest to konieczne.

Informacje ogólne

- Informacje o sekcjiPowinien to być bardziej szczegółowy opis projektu - może zawierać informacje o użytkownikach, ich rolach, niektórych bardziej zagmatwanych przypadkach, zrzutach ekranu itp.

- Makietymiejsce na linki do zasobów makiet UI/UX, jeśli takie istnieją.

• Inne informacje, takie jak Dostęp do serwerów lub Integracja z zewnętrznymi interfejsami APIPrzykłady obejmują adres url instancji staging, współdzielone niewrażliwe (!) poświadczenia dostępu, linki do dokumentacji, niektóre instrukcje itp.

Instalacja

- Wymagania: warunki wstępne, które muszą zostać spełnione przed rozpoczęciem konfiguracji aplikacji, np. instalacja narzędzi zewnętrznych.

- Konfiguracjainstrukcje krok po kroku, których należy przestrzegać, aby uruchomić projekt.

- Ustawieniaopisują, gdzie przechowywane są ustawienia lokalne i zawierają instrukcje dotyczące odbierania własnych ustawień.

- Konfiguracja lokalnaJeśli istnieją przypadki konfiguracji lokalnej, jest to dobre miejsce na wyjaśnienie.

Rozwój

Ta sekcja jest idealnym miejscem na instrukcje, takie jak rozwój funkcji, poprawki błędów, poprawki, wspólne funkcje, testowanie, przewodniki po stylach, organizacja kodu, inne narzędzia programistyczne używane w projekcie (np. strażnicy lub dockery) i tak dalej. Nie zapomnij wspomnieć o wszystkich zasadach, które każdy zespół członek powinien wiedzieć.

Wdrożenie

Zapewnij jasne instrukcje krok po kroku dla każdego środowiska i wszystko, co "warto wiedzieć" podczas wdrażania.

Inne pomysły na oddzielne sekcje

- Dokumentacja API

- Dziennik zmian

- Zasoby zewnętrzneMiejsce na wszelkiego rodzaju linki, które mogą być pomocne.

- Stos aplikacji: lista stosu aplikacji, których używamy w projekcie - może zawierać krótki opis i nazwę dostawcy.

Zespół

Dyskusyjne jest, czy konieczne jest pokazywanie aktualnych członków zespołu projektowego (github domyślnie udostępnia pełną listę współpracowników), ale zawsze miło jest zobaczyć swoje imię i nazwisko jako jednego z autorów projektu. Jeśli to zrobisz, aktualizuj ją tak często, jak to możliwe.

Kilka słów na koniec

Pamiętaj: każdy projekt jest wyjątkowy, podobnie jak jego dokumentacja. Nie ma jednego świetnego rozwiązania do pisania README. Wystarczy postępować zgodnie z ogólnymi wskazówkami, a najważniejszą rzeczą jest, aby zawsze pamiętać o refaktoryzacji, która również łączy się z README. Zawsze dobrze jest spojrzeć na dokument jako całość i przemyśleć go, jeśli coś musi być wyświetlane w inny sposób.

Jeszcze jedno: "instrukcje" są kluczowe, więc pisz je często. Dziękuję!

Czytaj więcej:

• Zasada otwarte-zamknięte. Czy kiedykolwiek będę musiał jej użyć?
• Jak napisać dobry i jakościowy kod?
• Vuelendar. Nowy projekt Codest oparty na Vue.js