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

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

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

Роздуми в цій статті ґрунтуються на моєму досвіді роботи над Landscape, продуктом для системного адміністрування з довгою історією в Canonical. Наша команда складається з бекенд-інженерів, веб-інженерів, авторів документації, менеджерів продуктів та UX-дизайнерів. Як і багато команд, відповідальних за зрілий продукт, ми поєднуємо поточне обслуговування та запровадження нових функцій, часто співпрацюючи з іншими інженерними командами.

Документаційно-орієнтоване розроблення: що це означає на практиці

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

Документація тут означає не тільки документацію для користувачів. Вона включає документацію з проектування, документацію для користувачів і будь-яку внутрішню документацію, яка використовується для співпраці всередині команди або з іншими командами. На практиці цей процес дав нашій роботі над функціями більш чітку послідовність.

Ось як виглядає документаційно-орієнтоване розроблення у нашій команді:

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

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

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

До моменту завершення функції документація також завершена, не тому, що її писали на поту, а тому, що вона допомогла формувати роботу в процесі.

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

Що не працювало до прийняття нового підходу

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

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

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

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

Суттєві зміни: Документація як частина інженерії

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

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

Приклад: уникнення витратної помилки

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

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

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

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

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

Що змінилося з часом

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

Документація для користувачів як частина процесу розробки

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

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

Чіткі артефакти та краща співпраця

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

Зміна культури команди

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

Обмеження

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

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

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

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

Погляд у майбутнє

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

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