Табыстар:
- Мақсатты аудиторияға және AI бар көзге негізделген README, docstring және changelog жобаларын жасау мүмкіндігі
- Құжаттамадағы «не/қалай» және «неге» қабаттарын бөлу және адам ретінде «неге» қосу мүмкіндігі
- Орнату қадамдарын жеке іске қосу және құжатты кодты өзгертудің бір бөлігі ету арқылы тексеру
Бағдарламалық жасақтаманың ең жиі еленбейтін, бірақ ең ұзақ қызмет ететін бөлігі құжаттама болып табылады. Код бірнеше айдан кейін де оқылады; Оны жазған адам кетіп, контекст ұмытылып, жазылғаны ғана қалады. Жақсы README (жобаның не екенін және оны орнату және іске қосу жолын түсіндіретін кіріспе құжат), түсіндірме кодтық түсініктемелер және жаңартылған API құжаттамасы (интерфейсті пайдалану жолын түсіндіретін анықтама) команданың жылдамдығын тікелей анықтайды. AI құжаттамадан «жазу шаршауының» көп бөлігін алады, бірақ ол тұзақпен бірге келеді: AI кодтан не істейтінін шығара алады, бірақ көбінесе оның неге осылай жасалғанын біле алмайды.
Бұл бөлімде сіз README, кодтық түсініктеме, құжат тізбегін (функция/сыныпқа жазылған түсініктеме блогы), API құжатын және AI көмегімен өзгерту журналын жасауды үйренесіз; және құжаттаманың ең құнды бөлігін адами түрде қалай сақтауға болады: «неге».
«Не» мен «Неге» арасындағы айырмашылық
Құжаттаманың екі қабаты бар. Біріншісі не/қалай: «бұл функция тізімді сұрыптайды», «орнату үшін осы пәрменді іске қосыңыз». Оларды код пен құрылымнан шығаруға болады; Бұл жерде AI керемет. Екіншіден, неге: «неліктен біз бұл қызметті синхронды емес, асинхронды еттік», «неліктен бұл шекті мән 30 секунд», «неге біз бұл кітапхананы екіншісінен таңдадық». Бұл кодта жазылмаған; Бұл дизайн шешімдерінің, шектеулердің және өткен қайғының өнімі.
AI «неге» екенін білмейді; Ең дұрысы, бұл ақылға қонымды болжам жасайды - бұл қауіпті, себебі қате себеп мүлдем себепсізден де жаман. Сонымен, еңбек бөлінісі анық: AI «не/қалай» жобасын жасайды, сіз «неге» дегенді қосасыз. Ең құнды түсініктеме - бұл код айта алмайтын нәрсені айтатын пікір.
Кеңес: Кодтың өзі анық айтылған нәрсені түсініктемемен қайталамаңыз (мысалы, i = i + 1 // i бір-бірін көбейтіңіз). AI кейде мұндай артық түсініктемелерді шығарады; Оларды жойып, күшіңізді «неге» деген пікірлерге арнаңыз.
Қадам бойынша: AI көмегімен құжаттаманы құру
- Мақсатты аудиторияны көрсетіңіз. «Жаңадан бастап жатқан әзірлеуші», «осы API қолданатын сыртқы топ», «болашақ мен» — аудитория тіл мен тереңдіктің үнін белгілейді.
- Дереккөзді беріңіз. Шақыруға сәйкес кодты, бар README, мысалды пайдалануды қосыңыз. Дереккөзсіз құжат - жасандылыққа шақыру.
- Орналастыру құрылымы. README стандартты бөлімдері (мақсат, орнату, пайдалану, конфигурация, үлес), құжат жолына арналған жоба пішімі.
- «Неге» бос орындарды белгілеңіз. AI-дан оның себебін білмейтін шешімдерді «мұнда «неге» ескертуі қажет» деп белгілеуді сұраңыз; Содан кейін сіз сол бос орындарды толтырасыз.
- Тексеру. Іс жүзінде орнату қадамдарын орындаңыз; үлгі кодын көріңіз. Жұмыс істемейтін README README мүлде болмағаннан жаман.
Үш шағын корпус
1-жағдай — README жеделдетілген қосу. Ашық бастапқы құралдың README жоқ; Жаңа салымшылар орнатумен орта есеппен 2 сағат күресті. Топ AI-ға орнату сценарийлері мен package.json берді және құрылымдық README жобасын жасады, содан кейін қадамдарды өздері таза машинада орындап, екі жетіспейтін тәуелділікті қосты. Кейінгі салымшылар үшін орнату уақыты орташа есеппен 25 минутқа дейін қысқарды.
2-жағдай — «Неге» ойлап тапқан тұзақ. Әзірлеуші AI-дан күту уақытының жанындағы түсініктемені сұрады (тайм-аут=30). AI ақылға қонымды, бірақ дұрыс емес негіздеме жазды «жоғары желінің кешігуіне шыдау үшін»; нақты себеп төменгі ағындық қызметтің келісімшарт бойынша 30 секундтық шегі болды. Қате интерпретация кейінгі әзірлеушіні мәнді қажетсіз арттыруға әкеліп соқты, бұл оқиғаға әкелді. Сабақ: код иесі негіздемесін тексеруі керек.
3-жағдай — Docstring стандарты автоматтандырылды. 40 функциясы бар көмекші модульде құжат жолдары болмады. AI-ға жоба пішімі (Google стилі) берілді және әр функция үшін параметр, қайтару және ерекшелік сипаттамаларын шығарды; Әзірлеуші оларды қарап шығып, бірнеше қате түр туралы мәлімдемелерді түзетті. 40 функцияны құжаттау жарты күннен бір сағатқа дейін қысқарды.
Көшірілетін төрт үлгі
Құрылымдық README жобасы:
Мақсатты аудитория: {{мыс. жаңа қатысушы}}.Төмендегі файлдар негізінде README жобасын жазыңыз. Бөлімдер: Мақсат, мүмкіндіктер, талаптар, орнату, пайдалану, конфигурациялау, тестілеу, үлес. Нақты файлдардан орнату/іске қосу пәрмендерін шығарып алу; ОРНАТУ. "[ТЕКСЕРУ]" арқылы сенімді емес жерлерді белгілеңіз. Дереккөз: {{package.json / сценарийлер / үлгі коды}}
Docstring/API сілтемесі:
Осы функцияларға құжат жолын {{жоба стилі: Google/NumPy/JSDoc}} пішімінде жазыңыз: қысқа қорытынды, параметрлер (түр + мағына), қайтару, шығарылған ерекшеліктер, 1 қысқа мысал. Кодта анық айтылған нәрсені қайталамаңыз. "Неге" дегенді талап ететін дизайн шешімдерін "[НЕГЕ КЕРЕК]" деп белгілеңіз, ойдан шығарылған негіздеме жазбаңыз.{{code}}
«Неге» түсініктемесі үшін бос орындарды алып тастаңыз:
Бұл кодта келесі әзірлеуші «неге бұлай?» Деп сұрауы мүмкін. (сиқырлы сандар, әдеттен тыс шешімдер, уақытша шешімдер). Әрқайсысы үшін SKELETON пікірін беріңіз, бірақ дәлелді БЛАНК қалдырыңыз; Мен негіздеуді толтырамын.{{code}}
Changelog/PR мәлімдемесі:
Төмендегі айырмашылықтан {{өзгеріс журналының жазбасы / PR сипаттамасы}} жазыңыз. Пішім: Не өзгерді (пайдаланушы тілінде), Неліктен (мәселе: {{...}}), үзіліссіз өзгерту (бар болса), ол тексерілді ме. Техникалық жаргонды мақсатты аудиторияға бейімдеңіз.{{diff}}
Әлсіз шақыру / Күшті шақыру
Әлсіз: "Осы жоба үшін README жазыңыз."
Күшті: "Мақсатты аудитория: осы репоны алғаш рет клондайтын әзірлеуші. Тіркелген package.json, docker-compose.yml және сценарийлер/қалта негізінде Мақсаты, Талаптары, Орнату, Жұмыс, Тестілеу, Үлес бөлімдері бар README жобасын жазыңыз. Бұл файлдардан пәрмендерді шығарып алыңыз, олардың ешқайсысында екеніне сенімді болмаңыз, [Y] деп белгілемеңіз."
Күшті нұсқа аудиторияға, дереккөзге, құрылымға және «жаса, оны белгіле» ережесін береді; сондықтан құжат нақты файлдарға негізделген және тексерілетін орындар анық көрінеді.
Құжат түрі
AI жақсы жұмыс істейді
Адам қосады/тексереді
README орнату
қадам контуры
Қадамдарды орындаңыз және растаңыз
Docstring/API
Құрылымы, параметрі, түрі
Дұрыс түрі және «неге»
Кодтық түсініктеме
«Ол не істеп жатыр» қысқаша мазмұны
«Неге бұлай» деген негіздеме
Changelog/PR
бірінші жоба
Әсер және дәлдік
Архитектуралық шешім (ADR)
қаңқа
Нақты шешімдер мен ымыраға келу
Құжаттама техникалық қызмет көрсетуді қажет етеді
Құжаттың ең қауіпті аспектісі – ол жалған болса да шын болып көрінуі. Код өзгерген кезде және құжат жаңартылмаса, ол оқырманды белсенді түрде жаңылыстырады. AI жаңартуды жеңілдетеді: дифференцияны шығарып, «бұл өзгеріс құжаттың қай бөліктеріне әсер етеді?» Деп сұраңыз. сұрай аласыз. Бірақ бұл жаңартуды қамтамасыз ететін процесс — құжаттаманы жаңартуды кодты өзгертудің бір бөлігіне айналдырыңыз (PR қабылдау критерийі). AI жеделдетеді; Топ тәртіпті қалыптастырады.
Абайлаңыз: README ішіндегі орнату қадамдарын тексермей жарияламаңыз. «Бәлкім, жұмыс» құжаты жаңа әзірлеушінің алғашқы күнін бұзып, сенімін әлсіретуі мүмкін. Қадамдарды таза ортада өзіңіз орындаңыз.
Жалпы қателер
- Жасанды интеллектке сәйкес келетін «неге» дегенді алу. Жалған ақтау ақталмаудан да жаман; Код иесі дизайн себебін жазуы керек.
- Орнату қадамдары тексерілмейді. Жұмыс істемейтін README сенімді жояды.
- Кодты қайталайтын қажетсіз түсініктеме. Ол шу шығарады, нақты «неге» интерпретациясын жасырады.
- Мақсатты аудиторияны нақтыламау. Кімге жазылғаны түсініксіз құжаттың жаңа бастағанға да, сарапшыға да пайдасы жоқ.
- Жаңартуды процесстен бөлу. Құжат кодпен жаңартылмаса, ол тез жаңылыстырады.
Қысқаша айтқанда
AI құжаттамадан механикалық жүктеменің көп бөлігін алады: README жылдам жобалары, құжат тізбегі, API анықтамасы, өзгертулер журналы және PR сипаттамалары. Бірақ ол ең құнды қабат болып табылатын «неліктен» екенін біле алмайды және оны жасау қауіпті. Еңбек бөлінісі анық: AI «не/қалай» шығарады, сіз «неге» дегенді қосасыз. Аудиторияны көрсетіңіз, ресурстармен қамтамасыз етіңіз, құрылымды енгізіңіз, сәйкес келетін жерлерді белгілеңіз және әрбір орнату қадамын өзіңіз іске қосу арқылы тексеріңіз. Құжаттаманы кодты өзгертудің ажырамас бөлігі етіңіз.
Қолданбалы тапсырма
Құжаттары жоқ немесе ескірген модульді немесе шағын жобаны таңдаңыз. Алдымен «құрылымдық README жобасы» (немесе docstring) үлгісімен AI құрылымынан контурды жасаңыз; Дереккөзді және мақсатты аудиторияны беруді ұмытпаңыз. Содан кейін AI [ТЕКСЕРУ] немесе [НЕГЕ КЕРЕК] деп белгіленген әрбір нүктеден өтіңіз: орнату қадамдарын нақты орындаңыз және өз біліміңізбен «неге» дизайнын толтырыңыз. Қанша қадамды түзету керек екенін және қанша «неге» қосқаныңызды ескеріңіз.
бақылау парағы
- [ ] Құжаттамада мен «не/қалай» және «неге» қабаттарын ажыратамын.
- [ ] Мен AI «неге» дегенді жасамаймын, мен оны өзім қосамын.
- [ ] Мен сұрауға мақсатты аудитория мен нақты бастапқы файлдарды беремін.
- [ ] AI белгілеген [ТЕКСЕРУ] нүктелерін жеке орындау арқылы тексеремін.
- [ ] Мен кодты қайталайтын қажетсіз түсініктемелерді жоямын.
- [ ] Мен құжаттаманы жаңартуды кодты өзгертудің бір бөлігін жасаймын.