Zyski:
- Możliwość tworzenia wersji roboczych plików README, dokumentów i dzienników zmian w oparciu o grupę docelową i źródła za pomocą sztucznej inteligencji
- Możliwość oddzielenia warstw „co/jak” i „dlaczego” w dokumentacji i dodania „dlaczego” jako człowiek
- Weryfikacja kroków instalacji poprzez ich osobiste uruchomienie i uczynienie dokumentu częścią zmiany kodu
Najczęściej zaniedbywaną, ale najdłużej trwającą częścią oprogramowania jest dokumentacja. Kod jest czytelny nawet po miesiącach; Osoba, która to napisała, odeszła, kontekst został zapomniany i pozostało tylko to, co zostało napisane. Dobry README (dokument wprowadzający wyjaśniający, czym jest projekt oraz jak go zainstalować i uruchomić), objaśniające komentarze do kodu i aktualna dokumentacja API (odniesienie wyjaśniające, jak korzystać z interfejsu) bezpośrednio determinują szybkość działania zespołu. Sztuczna inteligencja eliminuje wiele „zmęczenia pisaniem” dokumentacji — ale wiąże się z pułapką: sztuczna inteligencja może wywnioskować z kodu, co robi, ale często nie wie, dlaczego robi to w ten sposób.
W tej części dowiesz się, jak tworzyć plik README, komentarz do kodu, dokumentację (blok komentarza pisany dla każdej funkcji/klasy), dokument API i dziennik zmian za pomocą sztucznej inteligencji; i jak po ludzku zachować najcenniejszą część dokumentacji: „dlaczego”.
Rozróżnienie między „co” i „dlaczego”
Istnieją dwie warstwy dokumentacji. Pierwsza to co/jak: „ta funkcja sortuje listę”, „uruchom to polecenie, aby zainstalować”. Można je wyodrębnić z kodu i struktury; AI przoduje tutaj. Po drugie, dlaczego: „dlaczego sprawiliśmy, że ta usługa jest asynchroniczna, a nie synchroniczna”, „dlaczego ta wartość graniczna wynosi 30 sekund”, „dlaczego wybraliśmy tę bibliotekę, a nie inną”. Nie są one zapisane w kodzie; Jest to produkt decyzji projektowych, ograniczeń i problemów z przeszłości.
AI nie wie „dlaczego”; W najlepszym razie tworzy rozsądne przypuszczenie – co jest niebezpieczne, ponieważ zły powód jest gorszy niż żaden powód. Zatem podział pracy jest jasny: sztuczna inteligencja opracowuje „co/jak”, ty dodajesz „dlaczego”. Najcenniejszy komentarz to ten, który mówi to, czego kod nie może powiedzieć.
Wskazówka: nie powtarzaj w komentarzu tego, co sam kod wyraźnie mówi (np. i = i + 1 // zwiększ i o jeden). Sztuczna inteligencja czasami generuje takie niepotrzebne komentarze; Wyeliminuj je i poświęć swoją energię na komentarze „dlaczego”.
Krok po kroku: Generowanie dokumentacji za pomocą sztucznej inteligencji
- Określ grupę docelową. „Programista dopiero zaczynający”, „zewnętrzny zespół, który będzie korzystał z tego interfejsu API”, „ja z przyszłości” – odbiorcy nadają ton językowi i głębi.
- Podaj źródło. Dodaj odpowiedni kod, istniejący plik README i przykładowe użycie do zachęty. Dokument niepochodzący z źródła jest zaproszeniem do fabrykacji.
- Struktura impozycji. Standardowe sekcje pliku README (cel, instalacja, użycie, konfiguracja, wkład), format projektu dla dokumentacji.
- Zaznacz spacje „dlaczego”. Poproś sztuczną inteligencję, aby oznaczyła decyzje, których uzasadnienia nie zna, jako „tu wymagana jest uwaga „dlaczego””; Następnie wypełniasz te puste miejsca.
- Zweryfikować. Właściwie wykonaj kroki instalacji; wypróbuj przykładowy kod. Plik README, który nie działa, jest gorszy niż żaden plik README.
Trzy mini etui
Przypadek 1 — przyspieszone wdrożenie README. Brakowało pliku README narzędzia open source; Nowi autorzy zmagali się z instalacją średnio przez 2 godziny. Zespół przekazał AI skrypty instalacyjne i plik package.json oraz przygotował ustrukturyzowany plik README, a następnie samodzielnie wykonał kroki na czystej maszynie i dodał dwie brakujące zależności. Czas instalacji kolejnych autorów skrócił się średnio do 25 minut.
Przypadek 2 — Wymyślona pułapka „dlaczego”. Deweloper poprosił sztuczną inteligencję o komentarz obok wartości limitu czasu (limit czasu = 30). Sztuczna inteligencja napisała rozsądne, ale niepoprawne uzasadnienie „aby tolerować duże opóźnienia w sieci”; prawdziwym powodem był umowny limit 30 sekund usługi niższego szczebla. Błędna interpretacja doprowadziła kolejnego dewelopera do niepotrzebnego zwiększenia wartości, co doprowadziło do incydentu. Lekcja: właściciel kodu musi zweryfikować uzasadnienie.
Przypadek 3 — Standard Docstring został zautomatyzowany. Moduł pomocniczy z 40 funkcjami nie miał żadnych dokumentów. Sztuczna inteligencja otrzymała format projektu (styl Google) i wygenerowała opisy parametrów, zwrotów i wyjątków dla każdej funkcji; Deweloper sprawdził je i poprawił kilka nieprawidłowych deklaracji typu. Dokumentowanie 40 funkcji skróciło się z około pół dnia do godziny.
Cztery szablony do kopiowania
Ustrukturyzowany projekt README:
Grupa docelowa: {{np. nowy współpracownik}}. Napisz wersję roboczą pliku README na podstawie poniższych plików. Sekcje: Cel, funkcje, wymagania, instalacja, działanie, konfiguracja, testowanie, wkład. Wyodrębnij polecenia instalacji/uruchamiania z rzeczywistych plików; DOPASOWYWANIE. Zaznacz miejsca, których nie jesteś pewien, klikając „[WERYFIKUJ]”. Źródło: {{package.json / skrypty / przykładowy kod}}
Dokumentacja/odniesienie do API:
Napisz dokumentację do tych funkcji w formacie {{project style: Google/NumPy/JSDoc}}: krótkie podsumowanie, parametry (typ + znaczenie), powrót, zgłoszone wyjątki, 1 krótki przykład. Nie powtarzaj tego, co WYRAŹNIE mówi kod. Oznacz decyzje projektowe wymagające „dlaczego” jako „[DLACZEGO KONIECZNE]”, a nie pisz sfabrykowanego uzasadnienia.{{code}}
Usuń spacje z komentarza „dlaczego”:
W tym kodzie następny programista może zapytać „dlaczego tak jest?” (magiczne liczby, nietypowe decyzje, obejścia). Do każdego z nich dodaj komentarz SZKIELET, ale uzasadnienie pozostaw PUSTE; Wypełnię uzasadnienie.{{code}}
Dziennik zmian/oświadczenie PR:
Napisz {{wpis do dziennika zmian / opis PR}} z poniższej różnicy. Format: Co się zmieniło (w języku użytkownika), Dlaczego (problem: {{...}}), Istotna zmiana (jeśli istnieje), Czy została przetestowana. Dostosuj żargon techniczny do grupy docelowej.{{diff}}
Słaba zachęta/silna zachęta
Słabe: „Napisz plik README dla tego projektu”.
Mocne: „Docelowa grupa odbiorców: programista klonujący to repozytorium po raz pierwszy. Na podstawie załączonych plików package.json, docker-compose.yml i scripts/folder napisz wersję roboczą pliku README z sekcjami Cel, Wymagania, Instalacja, Działanie, Testowanie i Wkład. Wyodrębnij polecenia z tych plików, nie twórz ich; zaznaczaj wszędzie, gdzie nie jesteś pewien, za pomocą [SPRAWDŹ]”.
Mocna wersja daje odbiorcy, źródło, strukturę i zasadę „zrób to, zaznacz”; tak, aby dokument opierał się na prawdziwych aktach, a miejsca wymagające weryfikacji były wyraźnie widoczne.
Typ dokumentu
AI radzi sobie dobrze
Człowiek dodaje/weryfikuje
Instalacja CZYTAJ MNIE
zarys kroku
Wykonaj kroki i potwierdź
Dokumentacja/API
Struktura, parametr, typ
Poprawny typ i „dlaczego”
Komentarz do kodu
Podsumowanie „Co on robi”.
Uzasadnienie „dlaczego to jest”.
Dziennik zmian/PR
pierwszy projekt
Wpływ i dokładność
Decyzja architektoniczna (ADR)
szkielet
Prawdziwe decyzje i kompromisy
Dokumentacja wymaga konserwacji
Najbardziej niebezpiecznym aspektem dokumentu jest to, że wydaje się prawdziwy, mimo że jest fałszywy. Kiedy kod się zmienia, a dokument nie jest aktualizowany, aktywnie wprowadza czytelnika w błąd. Sztuczna inteligencja ułatwia aktualizację: wystaw różnicę i zapytaj „na które części dokumentu wpływa ta zmiana?” możesz zapytać. Ale to proces zapewnia aktualność — niech aktualizacja dokumentacji będzie częścią zmiany kodu (kryterium akceptacji PR). AI przyspiesza; Zespół buduje dyscyplinę.
Uwaga: nie publikuj bez sprawdzenia kroków instalacji w pliku README. Dokument „prawdopodobnie działający” może zrujnować pierwszy dzień nowego programisty i podważyć zaufanie. Wykonaj te kroki samodzielnie w czystym środowisku.
Typowe błędy
- Uzyskanie „dlaczego” dopasowanego do sztucznej inteligencji. Fałszywe uzasadnienie jest gorsze niż brak uzasadnienia; Właściciel kodu powinien napisać powód projektu.
- Brak weryfikacji kroków instalacji. README, który nie działa, niszczy zaufanie.
- Niepotrzebny komentarz powtarzający kod. Wytwarza szum, zasłaniając prawdziwe interpretacje „dlaczego”.
- Brak określenia grupy docelowej. Dokument, który nie jest jasny dla kogo jest napisany, nie będzie przydatny ani dla nowicjusza, ani dla eksperta.
- Oddzielenie aktualizacji od procesu. Jeśli dokument nie zostanie zaktualizowany o kod, szybko stanie się mylący.
Podsumowując
Sztuczna inteligencja eliminuje większość mechanicznego obciążenia dokumentacji: szybkie wersje robocze README, dokumentacja, odniesienia do API, dziennik zmian i opisy PR. Nie może jednak poznać „dlaczego”, które jest najcenniejszą warstwą, a wymyślanie jej jest niebezpieczne. Podział pracy jest jasny: sztuczna inteligencja produkuje „co/jak”, ty dodajesz „dlaczego”. Określ odbiorców, zapewnij zasoby, narzuć strukturę, zaznacz odpowiednie miejsca i weryfikuj każdy etap instalacji, uruchamiając go samodzielnie. Uczyń dokumentację integralną częścią zmiany kodu.
Zadanie aplikacji
Wybierz moduł lub mały projekt, którego dokumentacji brakuje lub jest ona nieaktualna. Najpierw wygeneruj konspekt ze sztucznej inteligencji za pomocą szablonu „ustrukturyzowanej wersji roboczej README” (lub dokumentu); Pamiętaj o podaniu źródła i grupy docelowej. Następnie przejdź przez każdy punkt, w którym sztuczna inteligencja zaznaczyła [WERYFIKUJ] lub [DLACZEGO POTRZEBNE]: faktycznie wykonaj kroki konfiguracji i wypełnij „dlaczego” projektu własną wiedzą. Zwróć uwagę, ile kroków należy naprawić i ile „dlaczego” dodałeś.
lista kontrolna
- [ ] W dokumentacji rozróżniam warstwy „co/jak” i „dlaczego”.
- [ ] Nie każę AI wymyślać „dlaczego”, dodaję to sam.
- [ ] Podaję podpowiedź docelowym odbiorcom i rzeczywiste pliki źródłowe.
- [ ] Weryfikuję [WERYFIKUJ] punkty oznaczone przez AI, osobiście je wykonując.
- [ ] Eliminuję niepotrzebne komentarze powtarzające kod.
- [ ] Aktualizację dokumentacji czynię częścią zmiany kodu.