Я знайшов, що БУДЬ-яка документація краща, ніж НЕ. Відповідна сума зазвичай визначається кількістю часу, який ми маємо це зробити, або від того, наскільки ми ненавидимо телефонні дзвінки та електронні листи підтримки.
Здається, що члени вашої нинішньої команди мають певні нереалістичні сподівання на свої спогади, або вони соромляться своїх навичок письма та не бажають практикувати.
Я усвідомлюю, що перебуваю в меншості (англійський майор, який в аспірантурі потрапив до інженерії програмного забезпечення), тому що я не вважаю документацію справжнім завданням. Це цінний професійний інструмент. Можливо, мені не здається писати так важко, як деяким моїм колегам, але це здебільшого тому, що я маю більше практики. Я не вважаю проект закінченим, якщо в ньому немає документації, і я зазвичай пишу його з чисто егоїстичних причин: тому я можу дати людям щось читати замість того, щоб телефонувати на дзвінки та електронні листи, або я можу пригадати, про що ми говорили в минулому місяць або близько того, я можу посилатися на те, як я щось робив, якщо мені потрібно підтримати це посеред ночі.
Найкращий спосіб наблизитись до документації - це написати її ЯКЩО ВИ ЙДЕ, точно так само, як писати тестовий код. Дивно, як кілька попередньо написаних шаблонів (із заголовками, заглушками коду тощо) можуть зробити документацію простішою та швидшою. Таким чином ви можете зафіксувати зміни, як це відбувається, і у вас менше часу для покриття. Ви є більш ефективними таким чином, оскільки можете звертатися до документації так, як вам потрібно, і ви змінюєте її по ходу. Наприклад, у вікі, наприклад, полегшується оновлення, і ви можете уникнути проблем з версією документа, якщо найновіші та найбільші завжди в Інтернеті в тому самому місці, і ви можете просто надсилати посилання людям, яким потрібно їх прочитати.
Якщо ви витратите трохи часу на документування, ви ВСІ будете працювати швидше, особливо коли хтось новий приєднується до команди, оскільки їм не доведеться витрачати весь цей час на роздумування всього. Виявлення речей - це цікава частина наших завдань, але це не весело, коли вам доведеться це робити, поспішаючи налагодити виробництво. Ми всі заощадили б багато часу, якби всі написали ще пару заміток.
Чи є у вашої команди однакові проблеми з тестуванням чи написанням тестового коду? Якщо ні, то це буде простіше продати.
Ваша документація корисна багатьма способами:
1) Вам, прямо зараз, і вашим колегам, коли ви працюєте над проектом.
2) Вашим клієнтам. Наявність документації (включаючи схеми), яку можна показувати користувачам, полегшує обговорення на засіданнях, особливо якщо ви обговорюєте складні системи. Навіть якщо документація неповна, це місце, з якого слід почати.
3) людям, які успадкують вашу роботу (яка може бути навіть ви, через три роки). Багато моїх молодших колег думають, що запам'ятають речі назавжди. Я знаю, що не згадаю його минулого цього тижня, якщо не запишу його. Наявність документації позбавляє вас від необхідності витратити півдня, щоб запам'ятати, як ви щось структурували, і вам доведеться все це з'ясувати.
4) Вам та іншим, якщо ситуація стає політичною чи суперечливою. Як хтось, хто веде нотатки на зустрічах, щоб пробудити себе і боротися з нудьгою, я часто був єдиним із письмовою версією рішення. Людина, яка її записала, виграє суперечку. Згадайте це наступного разу, коли хтось скаже: "Згадайте, що ми зустрічалися минулої зими в конференц-залі 4, коли ми переходили через X? Фред був там, а хто той хлопець із бухгалтерії?"