Що з відразою до документації в галузі?

Здається, є відраза до написання навіть найпростішої документації. Наш проект README відносно голий. У документах немає навіть оновлених списків залежностей.

Чи є щось, про що я не знаю в галузі, що змушує програмістів не любити писати документацію? Я можу набрати абзаци документів, якщо це потрібно, то чому ж інші настільки протистоять цьому?

Що ще важливіше, як я переконаю їх, що написання документів допоможе нам заощадити час і фрустрацію в майбутньому?

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

Натомість зосередьтеся на проблемі та можливих рішеннях.

1. Напишіть собі хорошу документацію

Можливо, не реально очікувати, що всі члени вашої команди спрямовуватимуть свої зусилля на те, що ви бачите як проблему. Це особливо актуально, якщо ви відносний новачок у команді. Я б ризикну здогадатися, що ви є, тому що якби ви були членом команди, здається, цілком ймовірно, ви вже вирішили це питання на початку.

Подумайте, замість цього, працюйте над ціллю написати гарну документацію самостійно та змусити людей її використовувати. Наприклад, якщо хтось із моєї команди запитує мене, де знаходиться вихідний код для проекту A чи яка спеціальна конфігурація потрібна проекту A, я вказую їх на вікі-сторінку Project A.

Якщо хтось запитує мене, як написати нову реалізацію Factory F, щоб налаштувати річ для Клієнта C, я скажу їм, що це знаходиться на сторінці 10 керівництва для розробників.

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

2. Доведіть цінність вашої документації

Переконайтеся, що ви користуєтесь кожною можливістю, щоб вказати, де документація доводить свою цінність (чи мала б, якщо вона використовується). Постарайтеся бути тонкими і уникайте "я тобі це сказав", але цілком законно говорити такі речі

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

або

Я такий радий, що записав кроки для виконання завдання T. Мені дуже не важливо, якщо ніхто більше ніколи його не використовує - це вже заощадило мені більше часу, ніж те, що я витратив на його написання.

3. Отримайте управління на борту

Після кількох випадків, коли наявність документації суттєво економить час / гроші, ви, мабуть, помітите явну "відлигу" до документації. Настав час натиснути точку, почавши включати час документації у ваші оцінки (хоча, чесно кажучи, я зазвичай оновлюю / створюю документи під час тривалих процесів, таких як компіляції чи реєстрації). Особливо, якщо це нещодавній прокат, можливо, це не ставитиме під сумнів, але натомість розглядати його як нову практику, яку ви запроваджуєте з попереднього робочого місця (що це може бути).

Слово застереження: Більшість начальників не люблять змушувати людей робити що-небудь, особливо те, що не пов'язане безпосередньо із завданням, що підлягає сплаті, тому не очікуйте, що ця підтримка буде у формі мандату. Натомість, швидше за все, ви зможете дати вам відносно вільний доступ до написання більшої кількості документів.

4. Заохочуйте документацію, коли її бачите

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

Якщо ваша команда робить огляди коду, це час, коли ви можете залишити тонке слово або два, щоб заохотити хороші коментарі.

Дякую, що ви задокументували вирішення проблеми B в Framework G. Я про це не знав, і не думаю, що міг би зрозуміти, що ви робите без цього там.

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

Крім цього, це справді не ваша проблема, якщо ви не обіймаєте посаду керівника чи керівництва. Ви можете вести коня до води, але ви не можете змусити його пити. Якщо це не ваш кінь, ви, можливо, не будете щасливі, що спрагу, але все, що ви можете зробити - це заповнити корито.

У моєму досвіді є два основні фактори:

Терміни

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

Зміна

Відносно нова найкраща практика для розробників - знецінювати коментарі. Ідея полягає в тому, що зберігання інформації в двох місцях (код (включаючи тести) та коментарі навколо коду) призводить до великих витрат, щоб синхронізувати їх з невеликою користю. "Якщо ваш код настільки важко читати, що вам потрібні коментарі, чи не вдалося б краще витратити час на очищення коду?"

Я особисто навіть більше не буду дивитися на коментарі. Код не може брехати.

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

Тут грає ряд факторів:

1. Добре написаний код - це власна документація. За інших рівних умов краще написати чіткіший код, який говорить сам за себе, а не більше документації. Зробіть це, і вам потрібно буде змінити менше документації, коли ви зміните цей код.

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

3. Документацію потрібно писати лише один раз , а не двічі (один раз у вихідному коді та знову у посібнику програміста). Ось чому у нас є такі речі, як XML-коментарі та генератори документації. На жаль, використання таких інструментів може бути більш складним і громіздким, ніж просто писати документацію вручну, тому ви не бачите цих інструментів широко використовуваних.

4. Хороша документація забирає багато часу, і це важко зробити добре. За інших рівних умов написання нового коду може мати більше значення, ніж написання документації для вже існуючого коду.

5. Коли код змінюється, ви також повинні змінити документацію. Чим менше там документації, тим менше потрібно змінити.

6. Ніхто так і не читає документацію, то чому б це турбувати?

Слон у кімнаті: Програмісти не є (обов’язково) письменниками. Вони також не підлягають детальній реалізації своїх технічних реалізацій. Другий слон в кімнаті: Технічні письменники, як правило, не в змозі скласти деталі, корисні для майбутніх розробників (навіть якщо розробники подумають пояснити їм їх).

Складна система може з часом стати непорушною без належної документації. Код стає менш цінним, обернено пропорційним його скрутабливості [sic]. Вирішено, менеджмент наймає програмного інженера, який може читати розробники кодів та коаксифікувати дані, сплачує його за ставкою розробника та надає йому обов'язки документувати та вести документацію. Цей письменник може прочитати код і буде знати, які питання задавати, і заповнить деталі за необхідності. Так само, як у вас є відділ із забезпечення якості, у вас є відділ внутрішньої документації.

Код стане більш цінним, оскільки ви можете ліцензувати його третій стороні (тому що він може це зрозуміти), код можна буде легше перевірити та покращити / повторно визначити, вам буде краще використовувати повторно код навіть там, де ви можете легко визначити більш легкі версії свого програмного забезпечення, і ви зможете легше впроваджувати нових розробників у проект, ваші інженери із підтримки будуть любити працювати на вас.

Це ніколи не відбудеться.

Що ще важливіше, як я переконаю їх, що написання документів допоможе нам заощадити час і фрустрацію в майбутньому?

Це робить це?

Існує два типи документації:

Корисна документація

Документи, як використовувати готовий продукт, API, IP-адреси чи імена URL-адрес, які мають наші сервери тощо. В основному, все, що використовується важко і щодня. Неправильна інформація буде знайдена швидко та буде виправлена. Потрібно легко та легко редагувати (наприклад, онлайн-Wiki).

Марна документація

Документація, яка часто змінюється, мало хто цікавиться нею, і ніхто не знає, де її знайти. Як і поточний стан функції, що реалізується. Або необхідні документи у слові doc, сховані десь у SVN, оновлені 3 роки тому. Ця документація потребує часу для написання та час, щоб пізніше з’ясувати, що це неправильно. Ви не можете покластися на цей тип документації. Це марно. Це витрачає час.

Програмісти не люблять писати чи читати марну документацію. Але якщо ви зможете показати їм корисну документацію, вони її напишуть. Ми мали успіх із цим у моєму останньому проекті, коли представляли Wiki, де ми могли часто записувати всю потрібну нам інформацію.

Я б сказав, що головна причина - відсутність волі та нерозуміння функції документації. Існує ряд класів документації, які слід враховувати:

Документація щодо продукту / випуску

Це все, що виходить з вашим «готовим» продуктом. Це більше, ніж просто посібники, це README, журнали змін, HOW-TO тощо. Теоретично, ви можете уникнути того, щоб не писати їх, але ви закінчите продуктом, який люди не хочуть використовувати, або тягарем підтримки, який надмірно дорогий.

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

Це описує щось, що має бути відносно статичним. Оскільки численні споживачі можуть кодувати ваш API, він повинен бути достатньо стійким, щоб деяка проза, що описує його використання, мала значення. Опис того, які параметри підтримуються, якими можуть бути повернені значення та які помилки можуть бути викинуті, дозволить іншим користувачам зрозуміти ваш API на потрібному рівні абстракції - інтерфейсі (а не реалізації).

Коментарі до коду

Думається, що галузева думка щодо коментарів зараз не відповідає. Коли я вперше почав кодувати професійно, коментарі були неодмінною умовою написання коду. Тепер мода полягає в тому, щоб писати такий зрозумілий код, коментарі зайві. Я б ризикнув здогадатися, що це частково пов’язано з тим, що багато сучасних мов написано на набагато вищому рівні, і писати розбірливий код у Java, JavaScript, Ruby тощо можна легше, ніж це було в асемблері , C, FORTRAN тощо. Отже, коментарі мали набагато більшу цінність.

Я все ще вважаю, що в коментарях, що описують наміри розділу коду, або деякі деталі щодо того, чому певний алгоритм був обраний над більш очевидним (щоб уникнути надто завзятих рефакторинг-друзів, я не маю значення) t насправді потрібно виправити).

На жаль, існує багато корисливого самолюбства, раціоналізації та самообману, що приймає рішення програмістів не документувати. Реальність така, що, як і код, основною аудиторією документації є інші люди. Таким чином, рішення писати (чи не писати) документацію на будь-якому рівні - це те, що повинно прийматися на рівні команди. Що стосується більш високих рівнів абстракції, може бути більше сенсу, щоб хтось, крім розробників, це робив. Що стосується документації на рівні коментарів, то досягнення згоди щодо мети та наміру коментарів слід узгоджувати разом, особливо у командах зі змішаними здібностями та досвідом. Непогано, щоб старші розробники писали код, до якого молодші розробники не можуть підійти. Деякі добре розміщені та добре написані документи можуть дозволити команді працювати набагато ефективніше

Ось два мої центи.

1. Agile Manifesto стверджує, що "Працює програмне забезпечення над всеосяжною документацією", і не всі читають, щоб досягти "Тобто, поки в пунктах праворуч є значення, ми цінуємо предмети зліва більше".

2. На жаль, це звично для https://en.wikipedia.org/wiki/Code_and_fix, і документація не працює з цією моделлю (вона виходить із синхронізації).

3. Галузь розробки програмного забезпечення недостатньо регулюється Немає юридичної вимоги писати документацію.

4. Код самодокументації - поточна тенденція.

Сказавши це, я думаю, що там багато хорошої документації.

Документація потребує часу, і я підозрюю, що у багатьох розробників було занадто багато запусків із документацією, яка була гіршою, ніж марною. Вони отримують думку про те, що документування не тільки позбавить їх керівника (той самий хлопець, який продовжує скорочувати частину QA-графіку), але це не допоможе нікому, включаючи них.

Будь-який напівпристойний біт документації - це інвестиція у майбутнє. Якщо вам не байдуже майбутнє (тому що ви не думаєте, що не виходить за наступну зарплату, або тому, що думаєте, що це не буде вашою проблемою), то думка робити документацію надзвичайно болісна.

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

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

Хороший автор документації може спілкуватися різними мовами: мовою користувачів, мовою управління, мовою служб підтримки, мовою розробників. Завдання письменника документації - зрозуміти, що кодер спілкується, і перевести це у форму, яку можуть зрозуміти всі інші групи.

Коли ви очікуєте, що кодери розвиватимуть навички, необхідні для того, щоб стати хорошими комунікаторами (письмово чи іншим способом), кількість часу, витраченого на відточування основного набору навичок (кодування!), Зменшується. Чим далі він отримує свою зону комфорту (кодування та спілкування з іншими кодерами), тим більше часу та енергії знадобиться для того, щоб добре виконати завдання. Ви можете обґрунтовано очікувати, що професійний кодер бажає зосередити увагу насамперед на своїх основних компетенціях за рахунок всіх інших.

З цієї причини документацію (за винятком вбудованих коментарів до коду) краще залишити комунікаторам, а не кодерам.

Читання коду показує, як він працює. Він не може пояснити, чому : потрібні коментарі.

Читання коду показує назву методу та типи параметрів. Це не може пояснити семантику чи точний намір автора: потрібні коментарі.

Коментарі не замінюють читання коду, вони додають до нього.

Документація не виконується як код. Як результат, часто не існує ефективних циклів зворотного зв’язку, щоб переконатися, що документація існує та є повною. Це та сама причина, що коментарі до коду схильні гнити.

Дональд Кнут пропагував грамотне програмування як спосіб поліпшення якості програмного забезпечення, ефективно записуючи документацію з кодом. Я бачив декілька проектів, які досить ефективно використовували цей підхід.

Особисто я намагаюся дотримуватися сучасної тенденції збереження публічного API вашого коду як можна читабельніше, а також використовувати тестові одиниці для використання документів для інших розробників. Я думаю, що це частина більшої ідеї створення API-інтерфейсу у формі, яку можна досліджувати та виявляти. Я думаю, що цей підхід є частиною того, що HATEOAS намагається досягти за допомогою веб-сервісів.

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

Люди, які не люблять читати документацію, не люблять писати документацію. Дуже багато програмістів зроблять усе можливе, щоб уникнути ретельного читання документа.

Не фокусуйтесь на написанні, а зосередьтесь на читанні. Коли програмісти прочитають документацію та засвоїть речі з неї, вони побачать цінність і будуть набагато більш схильні їх написати.

Коли я розпочав свою теперішню роботу і взяв на себе апаратно-програмний проект від людей, які раніше працювали над ним, мені дали сто або більше сторінок ms word word, що описують систему. На виробництво повинно пройти кілька днів. Я дивився на це, можливо, двічі. Незважаючи на велику кількість інформації там, вона рідко відповідала на актуальні питання щодо системи, і навіть коли це було, швидше було подивитися на код.

Після достатнього подібного досвіду ви просто починаєте думати, навіщо турбуватися? Навіщо витрачати свій час на відповіді на запитання, які люди ніколи не задавали? Ви починаєте розуміти, як по-справжньому важко передбачити, яку інформацію люди будуть шукати в документації; вона неминуче наповнюється фактами, які виявляються марними, незрозумілими або очевидними, і не вистачає відповідей на найактуальніші питання. Пам'ятайте, виготовлення корисної документації - це спроба передбачити поведінку людини. Так само як дизайн інтерфейсу користувача навряд чи вдасться до того, як він пройшов багаторазові ітерації тестування та налагодження, так наївно думати, що можна писати корисну документацію, виходячи лише з очікувань того, як люди будуть інтерпретувати систему та що роль документації та її мови буде грати в цьому тлумаченні.

Я схильний вважати, що більша частина тиску для написання документації випливає з того, що це неприємна справа, і люди люблять винуватити один одного у виконанні неприємних справ ("Ви не їли свою фільбоїдну студію!").

ЗАРАЗ

Я не думаю, що документація є, в усіх відношеннях, безнадійною. Я думаю, що це безнадійно насамперед, коли люди розглядають документацію як цей додатковий тягар, який повинен бути виконаний до закінчення роботи, як останній шматочок очищення, через який слід поспішити, і як скриньку, яку потрібно перевірити. Документація - це те, що ви повинні працювати над аспектами свого дня, які ви завжди робите завжди. Я думаю, що електронна пошта - це особливо хороший спосіб зробити документацію. Додавши нову функцію, напишіть декільком людей швидкий електронний лист, у якому сказати, що це таке. Коли намалюйте нову схему, створіть PDF та надішліть його будь-кому, хто може зацікавити. Перевагами електронної пошти є:

1. Люди зазвичай перевіряють електронну пошту, тоді як ніхто не перебирається через папку під назвою "doc".

2. Електронна пошта існує в контексті, в оточенні інших електронних листів, де обговорюються особливості та пов’язані з ними функції та все інше, що відбувалося в той час.

3. Електронна пошта коротка та цілеспрямована і має тему.

4. Електронна пошта дозволяє людям, яким небайдуже, відразу ж задавати питання,

5. Електронну пошту можна легко шукати, оскільки люди використовують її для всього, а поштові клієнти впродовж багатьох років просунулися досить багато.

6. Якщо це повідомлення в електронному листі, принаймні одна людина знає, де його знайти.

Теоретично здається, що коментарі в коді також повинні бути "аспектами вашого дня, які ви завжди робите завжди", але якщо чесно, я ніколи не читав коментарів у коді. Я не впевнений, чому, але вони просто не дуже корисні, можливо, тому що не вистачає контексту, який вирішує електронна пошта.