Документуйте чорт з усього.
Нещодавно на Slashdot з’явилася нитка про стартову документацію, яка надихнула мене записати свої думки щодо документації.
Мої ключові моменти:
Принцип №1: Ніколи не робиться
Документація - це постійне зусилля, яке завжди буде відставати від того, що є у виробництві. Зміни вносяться тимчасово, речі переміщуються або припиняються або вводяться в експлуатацію навмання. Документація ніколи не наздожене.
Ви повинні продати людям, які платять рахунки, на вартість витрачання часу (а отже, і грошей) на оновлення діючої документації. Часто ці розмови йдуть так: "пам’ятайте, коли мені довелося витратити $ TIME, з'ясовуючи, як зламається $ THING? Ну, коли я закінчив, була ця технічна записка, яка деталізувала $ THING, так що наступний хлопець, який прийде разом, не буде треба все це розібратися ".
Ви повинні це зробити, навіть якщо ви ніколи не закінчите.
Принцип № 2: Єдине, що гірше, ніж жодна документація, є неправильною документацією
Це скоріше трюїзм, ніж принцип. Документація може заспокоїти вас помилковим розумінням того, що щось знаходиться у відомому стані, і якщо щось піде не так, то, можливо, у вас це буде запущено.
Важливо визнати цю проблему.
Принцип № 3: Ви пишете документацію для свого наступника
Коефіцієнти складають 95% всього, що ви робите, документа, на який ви більше ніколи не будете звертатися. Документація - це сукупність мудрості для майбутнього, а не для вас. Тож ви повинні припустити, що ваша аудиторія мало чи нічого не знає про специфіку того, як все є таким, яким вони є.
І буде наступник. Я не знаю про вас, але не планую перебувати в цих специфічних умовах до кінця свого життя. Можливості приходять і йдуть, а коли вони приходять, то іноді ви йдете. Але життя триває за вами, і чим плавніше ви можете зробити життя свого наступника тим кращим. Інакше у вас може бути колекція колишніх клієнтів, які непомітно говорять про вас невтішні речі. Мені подобається сказати, що це ті самі 50 хлопців, які працюють усюди в ІТ в Оттаві, тому що ви постійно скрізь нападаєте на них. Допомога вашому наступнику може відкрити вам двері в майбутньому.
Зараз певною мірою завжди є ступінь "звинувачення попереднього хлопця", коли виникають проблеми. Це частина бізнесу. Я це зробив сам. Але в декількох випадках, коли я ображав попереднього хлопця як якогось дебіла, я дізнався інакше, що він справді спільно вчився і більше знав про те, що відбувається, ніж я робив у той час.
Принцип №4: "Чому" часто важливіше, ніж "Як"
Дивлячись на систему, більшість з нас починає думати, думає, як, чому, чорт, це так? Майже завжди є дуже конкретні причини для зробленого вибору конфігурації. У цих умовах "Чому" диктує "Як", і ви повинні переконатися, що читач розуміє конкретні проблеми, що вирішуються під час вивчення залишків вашого куріння.
Принцип №5: Це повинно бути легко, інакше ви цього не зробите
Це означає, що ви повинні бути в курсі своїх інструментів, а також тих, хто збирається використовувати ваші інструменти.
Оновлення речей повинно бути простим. Якщо вам доводиться докладати будь-яких зусиль, ви знайдете виправдання, щоб уникнути цього, коли це найкраще зробити, що відразу після зміни.
Якщо ваші інструменти не прості у використанні для інших, вони не використовуватимуть їх. Це може бути особливо калічним у командному середовищі, оскільки чим більша команда, тим більше шансів на те, що ви зіткнетеся з членом команди, який не любить ваш вибір інструментів.
Особисто мені подобається вікі для документів. Однак проблема полягає в тому, що вікі не нав'язує вам структуру, тому структура повинна нав'язуватися зовні. Це завжди призводить до конфлікту десь, оскільки хтось має кращу / іншу ідею.
У деяких місцях я використовував документи, опубліковані у форматі Word та Visio, у форматі PDF, при цьому "останній" PDF вважався авторитетним. Це добре тим, що потім у вас є колекція, яку ви можете передати своєму роботодавцю / наступнику. Файли PDF-файлів, якщо належним чином датовані, можуть містити історичний запис про те, що трапилося, хоча той, через який нелегко переходити. Погано в тому, що мені не подобається Word або Visio і змушені були отримати базове розуміння цих інструментів, щоб ефективно передавати ідеї.
Мій нинішній роботодавець грає з ідеєю документів Word на порталі Sharepoint. Треба буде просто побачити, як далеко ми дістанемося