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

На жаль, жодна частина з величезних знань Жанін не була задокументована. Це стало справжнім викликом для тих, хто мав надалі підтримувати діяльність церкви, зокрема нового адміністратора офісу та нового пастора. Ніхто не мав уявлення, що робити в різних ситуаціях. Після від’їзду Жанін усім довелося заново відкривати всю цю інформацію — повільно та болісно, шматочок за шматочком.

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

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

Дехто ненавидить документувати процедури чи інші потенційно корисні знання. У них завжди знайдеться безліч виправдань:

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

Люди, які уникають фіксації важливої інформації або не користуються вже існуючою документацією, ігнорують один важливий факт:

Витрати на запис знань набагато менші, ніж витрати на їх повторне здобуття.

Так, створення будь-якої документації потребує часу. Аби уникнути втрати часу через неточну інформацію, необхідно також докладати зусиль для її актуалізації. Перспектива сісти та з нуля створити величезний довідник справді виглядає лякаючою. Суцільне «вибухове» написання документації – це складно, неприємно й неминуче призводить до прогалин у даних. Відтворити всю важливу інформацію постфактум майже неможливо.

Ключ до ефективної документації – це поступове створення та підтримка її в актуальному стані. Можливо, у вашому офісі досі немає книги процедур. Але ви можете почати її створення вже наступного разу, коли будете виконувати завдання, яке варто запам’ятати. Запишіть його та розмістіть у доступному місці. Формування й організація бази знань покроково не потребує значних зусиль, але може принести величезну користь.

Документування програмного забезпечення

Я працюю в сфері розробки програмного забезпечення вже давно. Дискусія про те, скільки інформації команда має документувати щодо вимог, планів та інших аспектів роботи, триває вже понад 25 років. Традиційно проєкти створювали специфікацію вимог до програмного забезпечення, що містила всю необхідну інформацію про те, що команда має розробити. Але мета полягає не лише в створенні документа. Головне – це формування спільної пам’яті команди, яка допоможе координувати роботу всіх учасників проєкту.

Складна й витратна частина процесу – це не написання вимог, а їх визначення. Записування отриманих знань у будь-якому вигляді – це радше транскрипція. Тому замість того, щоб відкидати специфікацію вимог як застарілий підхід до розробки програмного забезпечення, кожна команда має обміркувати: Яку інформацію варто зафіксувати? Який рівень деталізації є доречним? Хто має це записувати? Коли слід це робити? (Підказка: якщо ви пишете вимоги після написання коду, це вже не документація вимог, а їхнє зворотне проектування на основі того, що вже створено.)

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

Багато команд з розробки програмного забезпечення сьогодні намагаються мінімізувати письмову документацію, залишаючи лише найнеобхідніше, і віддають перевагу розмовам у форматі «just-in-time» для уточнення деталей. Це, безумовно, легше, ніж витрачати час на створення більш повної документації. Однак рішення про те, скільки інформації варто записувати, зводиться до питання ризику: який потенційний збиток може виникнути через відсутність документації порівняно з витратами на її ведення?

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

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

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

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

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

Можливо, штучний інтелект міг би позбавити нас таких проблем. Нещодавно я брав участь у серії онлайн-зустрічей з людьми з усього світу. Ведучий використовував Zoom AI Companion для створення підсумкового звіту про кожну зустріч. Результати вийшли доволі об’ємними й загалом (але не повністю) точними. Однак співвідношення корисної інформації до загального обсягу даних залишало бажати кращого. Транскрипт містив багато зайвої інформації з дискусій, яку не обов’язково було зберігати. ШІ не став для нас панацеєю.

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

Після того, як я піду

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

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

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

Вартість запису знань значно менша, ніж вартість їх здобуття.

Оригінальна стаття – To Document or Not to Document? That Is the Question, переклад – Олександра Горлович, ревью – Іван Вільчавський. Зображення з оригінальної статті.