Розглянемо спритний підхід. Я маю на увазі, якщо у вас є часові ресурси та прекрасні навички написання запису кожного дизайнерського рішення, яке ви приймаєте, разом із їх обґрунтуваннями, просто документуйте все. Реально кажучи, я припускаю, що ви не в такому становищі. Спритний підхід може допомогти у вирішенні складних проблем для документації обґрунтування: ви часто не знаєте, які обґрунтування були важливими до цього пізніше.
Давайте підійдемо до проблеми з цілісної точки зору. Ви, хлопці, обґрунтуєте своє рішення. Зараз вони потрапили в пастку посуду, мізки команди. Незважаючи на кількість отриманої кредитної документації, зберігання обґрунтування у програмі sqishyware не все так погано. Ми насправді дуже хороші, як вид, пам’ятаючи важливі речі. Тому кожна велика корпорація має "племінні знання", навіть коли ці корпорації прагнуть документувати все те племінне знання.
Тепер у вас є проблема. Ви виявляєте, що програмне забезпечення не дотримується обґрунтування. Вам добре, що ви зрозуміли, що є проблема, і визначили, що її потрібно вирішити! Це не завжди простий крок! Тож ми майже впевнені, що рішення - завантажити частину цього обгрунтування в документацію. Однак цього недостатньо. Ми ніколи не можемо забути другу половину головоломки, яка повторно завантажує обґрунтування в шпигунські вироби, коли потрібно приймати рішення. Я бачив безліч команд, які документують все як божевільне, але вміст насправді не організований, щоб допомогти приймати хороші рішення, тому вони врешті-решт забувають обґрунтування, навіть якщо їх записали .
Отже, у вас є процес у два етапи. Потрібно отримати обґрунтування з екіпажу та в документації. Тоді вам потрібно переконатися, що документація організована достатньо добре, щоб повернути раціонального в екіпіровку, коли вам це потрібно! Тепер я думаю, що у нас достатньо проблемної постановки, щоб зрозуміти, куди викличуться проблеми. Коли ви документуєте, ти зазвичай не знаєш, хто буде його шукати пізніше, або що вони шукають. Крім того, коли ви озираєтесь на документацію, ви зазвичай не знаєте, що шукаєте (у кращому випадку ви можете знати, коли).
Тож велика компанія може спробувати вирішити це у двох великих блоках. Спочатку вони можуть розробити вимоги, виходячи з того, що потрібно людям під час дослідження документації. Потім вони використовують ці вимоги для побудови процесу розробки зазначеної документації. І якщо я наважусь сказати так, то всі скаржаться, бо майже ніхто не знає , як саме повинна виглядати документація в перший день. Документація завжди неповна, а розробники завжди скаржаться на те, що процес занадто обтяжливий.
Час просунутися.
Моєю порадою було б докласти спритних зусиль, щоб покращити процес документування: цілих дев'ять ярдів, починаючи від шпигунського програмного забезпечення до документування та повертаючись до швейного. Визнайте наперед, що ви втратите деяку інформацію, оскільки ваш процес не є ідеальним, але це нормально, оскільки ви все ще намагаєтесь з'ясувати процес! Ви б пропустили більше, якби спробували створити один розмір, який підходить для всіх рішень.
Деякі конкретні ласощі, на які я дивлюсь: * Вивчіть неформальну документацію. Офіційна документація чудова, але забирає багато часу. Однією з цілей документації є звільнення інформації від шпигунських програм для розробників та розміщення їх на папері. Неофіційна документація мінімізує витрати на це.
- Прийміть ненадійні формати документації. Нічого не буде правильно з першого разу. Краще дістати дані та з’ясувати, як зробити їх надійними пізніше. Наприклад, ви можете задокументувати свої обгрунтування в блоці <rationale> </rationale> або щось подібне, що полегшить збирання даних згодом. Збереження обгрунтування в історії користувача поки що просто чудово!
- Ніколи не забувайте про цінність організації. Дізнайтеся, як ви, як команда, любите шукати обґрунтування в документації, і намагайтеся документувати це. У кожної команди буде інший процес. В одній з моїх команд ми ніколи не змогли знайти квиток, який мав би обґрунтування. Що ми могли б зробити - це знайти рядок коду, який мав значення, зробимо,
svn blameщоб з’ясувати, коли він змінився і чому, а потім перегляньте квитки. Після того, як ми були там, ми, як правило, виставляли всі необхідні обгрунтування в квитку. Що тільки працювало на нас, з’ясуйте, що для вас працює.
- Органічна документація може зростати з часом. Розробники нечасто знають, які обґрунтування є найважливішими в день, коли їм потрібно було написати. Зазвичай ми з'ясовуємо, які з них були важливими пізніше. Якщо у вас є процес догляду за документацією, яка дозволяє розробникам керувати власним маленьким садом обгрунтування, важливі з них піднімуться на поверхню. Ще важливіше, обгрунтування може змінитися. Ви можете усвідомити, що дві різні зміни, з двома різними обґрунтуваннями, справді найкраще описувались одним обґрунтуванням, яке працює для обох. Зараз між вами та рішеннями менше вмісту!