Прибуток:
- Можливість створювати README, рядки документів і чернетки журналу змін на основі цільової аудиторії та джерела за допомогою ШІ
- Можливість розділити рівні «що/як» і «чому» в документації та додати «чому» як людина
- Перевірка кроків інсталяції шляхом особистого запуску та включення документа до зміни коду
Частиною програмного забезпечення, якою найчастіше нехтують, але вона найтриваліша, є документація. Код читається навіть через кілька місяців; Людина, яка це написала, пішла, контекст забувся, і залишилося лише написане. Хороший README (вступний документ, який пояснює, що таке проект і як його встановити та запускати), пояснювальні коментарі до коду та актуальна документація API (довідка, яка пояснює, як використовувати інтерфейс) безпосередньо визначає швидкість команди. Штучний інтелект позбавляє документації від «втоми від написання», але він має пастку: штучний інтелект може зробити висновок із коду, що він робить, але часто не може знати, чому це робиться саме так.
У цьому розділі ви дізнаєтесь, як створювати README, коментар до коду, рядок документації (блок коментарів, написаний для функції/класу), документ API та журнал змін за допомогою AI; і як по-людськи зберегти найціннішу частину документації: «чому».
Різниця між "Що" і "Чому"
Існує два рівні документації. Перший — що/як: «ця функція сортує список», «запустіть цю команду для встановлення». Їх можна отримати з коду та структури; ШІ тут кращий. По-друге, чому: «чому ми зробили цю службу асинхронною, а не синхронною», «чому це обмеження становить 30 секунд», «чому ми вибрали цю бібліотеку замість інших». Вони не прописані в коді; Це продукт дизайнерських рішень, обмежень і минулого болю.
ШІ не знає «чому»; У найкращому випадку це обґрунтоване припущення, що є небезпечним, тому що неправильна причина гірша, ніж її відсутність. Тож розподіл праці зрозумілий: штучний інтелект пише «що/як», а ви додаєте «чому». Найцінніший коментар – це той, який говорить те, чого не може сказати код.
Порада: не повторюйте в коментарях те, що чітко сказано в самому коді (наприклад, i = i + 1 // збільшення i на одиницю). ШІ іноді створює такі зайві коментарі; Усуньте їх і присвятіть свою енергію коментарям «чому».
Крок за кроком: створення документації за допомогою ШІ
- Вкажіть цільову аудиторію. «Розробник, який тільки починає», «зовнішня команда, яка використовуватиме цей API», «я в майбутньому» — аудиторія задає тон мови та глибини.
- Наведіть джерело. Додайте відповідний код, наявний README, приклад використання до підказки. Документ без джерела є запрошенням до виготовлення.
- Структура верстки. Стандартні розділи для README (Призначення, Встановлення, Використання, Конфігурація, Внесок), формат проекту для рядка документації.
- Позначте прогалини «чому». Попросіть ШІ позначити рішення, для яких він не знає обґрунтування, як «тут потрібна примітка «чому»»; Потім ви заповнюєте ці пропуски.
- Підтвердити. Фактично виконайте кроки встановлення; спробуйте зразок коду. README, який не працює, гірше, ніж відсутність README взагалі.
Три міні-чохли
Випадок 1 — прискорена адаптація README. Відсутній README інструменту з відкритим кодом; Нові учасники боролися з установкою в середньому 2 години. Команда передала інсталяційні сценарії та package.json ШІ та склала структурований README, потім запустила самі кроки на чистій машині та додала дві відсутні залежності. Час встановлення для наступних учасників скоротився в середньому до 25 хвилин.
Випадок 2 — вигадана пастка «чому». Розробник попросив ШІ надати коментар до значення тайм-ауту (timeout=30). ШІ написав розумне, але некоректне обґрунтування «терпіти високу затримку мережі»; справжньою причиною було договірне 30-секундне обмеження нижньої послуги. Невірне тлумачення призвело до того, що наступний розробник без потреби збільшив значення, що призвело до інциденту. Урок: власник коду повинен перевірити обґрунтування.
Випадок 3 — Стандарт Docstring став автоматизованим. Допоміжний модуль із 40 функціями не мав рядків документації. ШІ отримав формат проекту (стиль Google) і створив описи параметрів, повернення та винятків для кожної функції; Розробник переглянув їх і виправив кілька неправильних декларацій типів. Документування 40 функцій скоротилося приблизно з півдня до години.
Чотири шаблони, які можна копіювати
Чернетка структурованого README:
Цільова аудиторія: {{напр. новий учасник}}. Напишіть чернетку README на основі файлів нижче. Розділи: Призначення, Особливості, Вимоги, Встановлення, Експлуатація, Конфігурація, Тестування, Внесок. Витягти команди встановлення/запуску з реальних файлів; ПРИМІТКА. Позначте ті місця, у яких ви не впевнені, за допомогою «[ПЕРЕВІРИТИ]». Джерело: {{package.json / скрипти / приклад коду}}
Посилання на Docstring/API:
Напишіть рядок документації для цих функцій у форматі {{стиль проекту: Google/NumPy/JSDoc}}: короткий підсумок, параметри (тип + значення), повернення, викинуті винятки, 1 короткий приклад. Не повторюйте те, що ЧІТКО сказано в коді. Позначайте дизайнерські рішення, які вимагають «чому», як «[ЧОМУ НЕОБХІДНО]», не пишіть сфабрикованих обґрунтувань.{{code}}
Видаліть пробіли для коментаря "чому":
У цьому коді наступний розробник може запитати "чому це так?" (магічні числа, незвичайні рішення, обхідні шляхи). Дайте коментар скелет для кожного, але залиште обґрунтування ПУСТИМ; Я заповню обґрунтування.{{code}}
Журнал змін/PR заява:
Напишіть {{запис у журналі змін / PR-опис}} із наведеної нижче різниці. Формат: що змінилося (мовою користувача), чому (проблема: {{...}}), критична зміна (якщо є), чи було перевірено. Пристосуйте технічний жаргон до цільової аудиторії.{{diff}}
Слабка підказка / Сильна підказка
Слабко: «Напишіть README для цього проекту».
Сильний: «Цільова аудиторія: розробник, який клонує це репо вперше. На основі вкладених файлів package.json, docker-compose.yml і папки scripts/ напишіть чернетку README з розділами «Призначення», «Вимоги», «Встановлення», «Експлуатація», «Тестування», «Внесок». Витягніть команди з цих файлів, не вигадуйте їх; позначте там, де ви не впевнені, за допомогою [VERIFY].»
Сильна версія дає аудиторію, джерело, структуру та правило «зроби це, познач це»; щоб документ базувався на реальних файлах, а місця, які потрібно перевірити, були чітко видні.
Тип документа
ШІ справляється добре
Людина додає/перевіряє
Встановлення README
поетапний контур
Виконайте кроки та підтвердьте
Docstring/API
Структура, параметр, тип
Правильний тип і "чому"
Коментар коду
Короткий зміст «Що він робить».
Виправдання «чому це».
Журнал змін/PR
перший проект
Вплив і точність
Архітектурне рішення (ADR)
скелет
Реальні рішення та компроміси
Документація потребує обслуговування
Найнебезпечніший аспект документа – це коли він виглядає правдивим, навіть якщо він неправдивий. Коли код змінюється, а документ не оновлюється, це активно вводить читача в оману. Штучний інтелект спрощує оновлення: створіть різницю та запитайте, на які частини документа впливає ця зміна? Ви можете запитати. Але це процес, який забезпечує актуальність — зробіть оновлення документації частиною зміни коду (критерій прийнятності PR). ШІ прискорює; Команда формує дисципліну.
Застереження: не публікуйте, не перевіривши кроки встановлення в README. «Імовірно робочий» документ може зіпсувати перший день нового розробника та підірвати довіру. Виконайте кроки самостійно в чистому середовищі.
Поширені помилки
- Отримати «чому», щоб відповідати ШІ. Фальшиве виправдання гірше, ніж відсутність; Власник коду повинен написати причину дизайну.
- Не перевіряються кроки встановлення. README, який не працює, руйнує довіру.
- Непотрібний коментар повторює код. Це створює шум, затуляючи справжні інтерпретації «чому».
- Без вказівки цільової аудиторії. Незрозуміло на кого написаний документ ні для новачка, ні для фахівця ні до чого.
- Відокремлення оновлення від процесу. Якщо документ не оновлено кодом, він швидко вводить в оману.
Підсумовуючи
AI знімає значну частину механічного навантаження з документації: швидкі чернетки README, рядок документації, посилання на API, журнал змін і PR-описи. Але воно не може знати «чому», яке є найціннішим шаром, і вигадувати його небезпечно. Поділ праці зрозумілий: штучний інтелект створює «що/як», а ви додаєте «чому». Укажіть аудиторію, надайте ресурси, накладіть структуру, позначте місця для розміщення та перевірте кожен крок інсталяції, виконавши його самостійно. Зробіть документацію невід’ємною частиною зміни коду.
Аплікаційне завдання
Виберіть модуль або невеликий проект, документація якого відсутня або застаріла. Спочатку згенеруйте схему за допомогою AI за допомогою шаблону «структурованого проекту README» (або рядка документації); Обов'язково вкажіть джерело і цільову аудиторію. Потім пройдіть кожну точку, де штучний інтелект позначив [ПЕРЕВІРИТИ] або [ЧОМУ ПОТРІБНО]: насправді виконайте кроки налаштування та заповніть дизайн «чому» своїми знаннями. Зверніть увагу, скільки кроків потрібно виправити та скільки «чому» ви додали.
контрольний список
- [ ] У документації я розрізняю шари «що/як» і «чому».
- [ ] Я не змушую штучний інтелект вигадувати «чому», я додаю це сам.
- [ ] Я вказую цільову аудиторію та фактичні вихідні файли.
- [ ] Я перевіряю пункти [VERIFY], позначені ШІ, особисто виконуючи їх.
- [ ] Виключаю непотрібні коментарі, які повторюють код.
- [ ] Я роблю оновлення документації частиною зміни коду.