Документація

Документація вимірює, чи може новачок дізнатися, що це за проєкт і як ним користуватися. Незадокументоване програмне забезпечення перекладає свою вартість на кожного користувача; задокументоване — масштабує знання своїх мейнтейнерів. Для рішення про залежність документація є ще й доказом дбайливості — проєкти, які себе пояснюють, як правило, себе й підтримують.

• Категорія: Інженерна якість (40% у межах категорії)
• Вага в загальному індексі: 8%
• Ключ метрики: documentation

Як обчислюється значення

Зважений контрольний список:

Шари: від необхідного до виявлюваного

• README (30) — це парадні двері; якщо його немає, ніщо інше не читається.
• Каталог docs (25) позначає документацію, що переросла один файл — зазвичай посібники, довідку чи нотатки про архітектуру.
• Сайт документації (15) сигналізує про стале інвестування: зверстана, зручна для навігації документація для користувачів, а не для відвідувачів репозиторію.
• Опис, теми та wiki (30 разом) — це метадані виявлюваності: вони визначають, чи можна проєкт узагалі знайти та класифікувати — людям, індексам пакетів і, дедалі частіше, інструментам ШІ.

Як читати результат

• Вимірюється наявність, а не якість тексту — чесна межа зовнішньої інспекції (див. сигнали, а не гарантії).
• Перечитуйте разом зі здоров'ям спільноти: README перетинається як спільний фундамент, але дві метрики відповідають на різні питання — чи можна це вивчити та чи можна в цьому брати участь.

Як покращити значення

• Вести змістовний README: призначення, встановлення, мінімальний приклад, посилання далі.
• Переносити документацію, що розростається, у docs/ і публікувати її як сайт (GitHub Pages чи будь-який генератор) — ці два кроки разом несуть 40 балів.
• Задати опис і теми репозиторію; увімкнути wiki там, де вона відповідає робочому процесу проєкту.

Дивіться також: здоров'я спільноти · Інженерна якість