Проблеми TypeScript у світі React-додатків вiд Iллi Климова на React fwdays | 27 березня
×Закрыть

Навіщо дотримуватися документування на проєкті і хто це повинен контролювати

Мене звати Інна Козак, я Founder of Jungle Courses, CEO в Jungle Consulting, менторка курсів QA та PM.

У статті поговоримо про документування ІТ-проєктів на різних стадіях життєвого циклу: навіщо взагалі документувати, яка від цього користь, хто має вести документацію та скільки це може коштувати проєкту. Хочу поділитися спостереженнями, які виникли під час роботи над різними проєктами на різних позиціях: тестувальника та менеджера. А також розповісти, як це — працювати без документації взагалі. Стаття спрямована більшою мірою на менеджерів і тестувальників.

Отже, давно відома практика витрачати ресурси на документування. Сучасний аутсорс-ринок пропонує послуги з документування ІТ-проєктів як must-have для успішного бізнесу. Замовив і забув. Але яка справжня користь документування на проєкті? І чи справді спеціаліст зовні зможе дати таку користь?

Ілюстрація Аліни Самолюк

Проблема документування на продуктових проєктах

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

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

Отже, основний недолік — брак інформації. Де її взяти?

  1. Збирати інформацію по частинках в кожного учасника команди.
  2. Піднімати історію тасків/фіч/багів.
  3. Починати описувати роботу проєкту/фіч.
  4. Інше.

Проте не все так просто з кількох причин:

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

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

А що в аутсорсі

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

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

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

Складні проєкти можуть обрости тоннами проблем через найменші технічні баги чи непорозуміння між людьми. Клієнт починає звинувачувати найману компанію через «фальшиві обіцянки». Виконавець цим незадоволений. Слово за слово — і рутинний баг роздувається до величезних розмірів.

Вихід: налагоджена комунікація та документування від А до Я.

Що таке документація на проєкті. Яка вона буває

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

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

Усю документацію можна розділити на дві основні категорії:

  1. Product documentation
  2. Process documentation

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

  • System documentation — документи, що описують саму систему та її частини. Це Requirement documents, Design decisions, Architecture descriptions, Program Source code, Testing documents.
  • User documentation — це інструкції, які підготовлені переважно для кінцевих користувачів продукту та команди підтримки. Це Tutorials, User guides, Troubleshooting manuals, Installation, Reference manuals.

Process documentation описують процес. Можуть бути Standards, Project plans, Test schedules, Reports, Meeting notes тощо.

Чим документи відрізняються від проєкту до проєкту

Усе починається з вимог Product requirement document, однак бувають винятки. Тут можна практикувати, хто як вміє. Головне — описати функціональні вимоги. Вони можуть містити Business rules, User stories, Use cases тощо. Хорошою практикою є опис таких основних розділів:

  1. Roles and responsibilities.
  2. Team goals and business objective.
  3. Background and strategic fit.
  4. Assumptions.
  5. User stories.
  6. Acceptance criteria.
  7. User interaction and design.
  8. Questions.
  9. Not doing.

На деяких проєктах відбувається писанина заради писанини. Інші — взагалі не витрачають ресурси на такі детальні розділи. Це й не дивно: погляньмо на два останні розділи Questions та Not doing — як взагалі можливо описати всі питання та фічі, які команда не буде розробляти?

Оскільки команда розв’язує проблеми під час реалізації проєкту X, у неї неминуче виникає багато питань. Ми почали таку практику: записували всі ці запитання та моніторили їх. Здавалося б, це нереально, але нам хотілося мати такі детальні звіти для відстежування будь-якої незрозумілої чи конфліктної ситуації. За якийсь час ми отримали результат. Але кожного разу, стикнувшись з проблемою, можна було «полистати» попередні обговорення. Зазвичай 80% вже мали рішення та були задокументовані кілька місяців тому. Так, про них просто забули чи не звернули на них уваги. А коли настала черга конкретного розгляду питання чи навіть розробки — виявилося, у команди вже є рішення!

User experience design починається на стадії вимог і проходить усі стадії розробки, охоплюючи етапи тестування та вихід в production. Процес проєктування UX містить User personas, User scenario, Scenario map, User story map, UX style guide, Site maps, Wireframes, Mock-ups, Prototypes, User flow schemes, Usability testing reports.

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

Software architecture document. Документування всіх архітектурних рішень вимагає багато зусиль. Наприклад, вирішили, задокументували, працюємо. Але реальність інша: під час розробки щось пішло не так.

З іншого боку, важко, наприклад, розробляти продукт без задокументованих Architecture & Design Principles. Якщо планували структурувати рішення за допомогою архітектури мікросервісів, то варто описати Solution details, майбутні модулі та компоненти тощо.

Quality assurance documentation. Серед найпопулярніших: Quality management plan, Test strategy, Test plan, Test case specifications, Test checklists. Якщо на вашому проєкті немає тестувальників, то й документації точно не буде. Якщо відділ тестувальників невеликий, вони зазвичай обмежуються тест-кейсами та чек-листами.

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

User documentation. Категорії User documentation також можуть розрізнятися між собою. Їх структурують відповідно до різних завдань користувача та різних рівнів досвіду. Це можуть бути end-users, support, system administrators.

Документація для кінцевих користувачів має якомога стисліше пояснити, як програмне забезпечення може допомогти вирішити їхні проблеми. Деякі частини User documentation замінюються на Onboard training. Але для складних систем необхідні User guides, Video tutorials, Wiki pages, FAQs, Embedded assistance, Support portals, etc.

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

У документах для команд підтримки зазвичай використовують Functional description, що описує функціональні можливості системи, та System admin guide, що пояснює різні типи поведінки системи в різних середовищах та інших системах, вказівки щодо вирішення різних ситуацій тощо.

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

Часто support-команді потрібно розуміти проєкт від А до Я, щоб мати змогу дослідити проблему на запит користувача. Як і в тестуванні: неможливо повністю протестувати продукт. Неможливо цілком описати продукт, передбачити всі варіанти розвитку подій, врахувати всі побажання користувача тощо.

Скільки коштує документування

Скільки коштує година роботи розробника/тестувальника над документацією? Ймовірно, стільки ж, як година розробки чи тестування. Є варіант попросити допомоги спеціального Technical Writer, який може бути як частиною команди, так і залучатися зовні.

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

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

Порахуємо загальну суму. Ви платите, наприклад, $100 на годину за 8–10 осіб, які можуть не знати всіх потрібних проєкту нюансів. Або віддаєте ті ж $100 на годину за роботу 4–5 людей, що досконало розуміють процеси. Здавалося б, більше — краще! Але ні, результат визначає не кількість людей, а такі фактори:

  • наявність у команди досвіду в подібних проєктах;
  • додаткові («запасні») фахівці в компанії підрядника, готові підмінити;
  • система навчання на робочому місці, наставники чи ментори;
  • налагоджена система менеджменту (не тільки проєктного, а й щодо операційних процесів на рівні компанії: фінанси, комунікації, документація).

Висновок один: процес створення документації такий само ресурсно-витратний, як розробка чи тестування.

Хто крайній

Уявімо проблему на проєкті. Без належної комунікації та документації, так званих доказів, починається пошук «винних». Винними можуть бути всі, вся команда і замовник теж.

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

Але можна призначити контролюючого, який буде вести шаблони документів, пінгувати інших членів команди, дописувати самостійно, де необхідно. Хто ця людина? PM? Technical Writer? А хто володіє всебічними знаннями про продукт найбільше в команді?

Наприклад, на проєкті X настав час, коли необхідно документувати вже наявні рішення. Менеджер делегує це зовнішньому Technical Writer. Практика ця, прямо кажучи, нічого не дала. Writer гарно знав англійську мову і кілька разів на тиждень приходив в офіс, щоб розпитати про якісь деталі проєкту. За кілька місяців роботи ми отримали User guide, який далеко не все покривав. Потім його дописувала QA-команда. А з Functional documentation у Technical Writer взагалі не склалося.

Загалом знову минуло багато часу на пояснення. Відривалася від роботи команда, а в результаті — потрібно виправляти. Вихід знайшовся один: залучити QA-команду до створення документації.

Роль QA-інженера у поліпшенні продукту через документи

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

Що повинен робити QA Engineer у щоденному робочому процесі:

  • обговорювати ризики;
  • підтверджувати строки;
  • стежити за ранніми результатами демоверсії;
  • знаходити проблеми та дефекти;
  • допомагати з тестовими даними (для розробників).

Що має робити інженер із забезпечення якості на етапі планування:

  • обговорювати питання і ризики;
  • роз’яснювати Use cases;
  • визначати зовнішні інтеграції;
  • планувати тести для User stories;
  • планувати релізи з термінами виконання;
  • попередньо розглядати можливі проблеми/дефекти;
  • визначати нефункціональні вимоги.

Що повинен робити QA Engineer на етапі релізу:

  • тестування User stories, щоб передбачити реальні проблеми якнайшвидше та уникнути повторної роботи;
  • скоротити ручну роботу для тестування/швидкого тестування.

Що має зробити інженер із забезпечення якості після закінчення релізу/виходу в production:

  • розподілити регресійне тестування;
  • проаналізувати, як можна скоротити час;
  • синхронізуватися з автоматизованим тестуванням;
  • спілкуватися, щоб розв’язувати проблеми якнайшвидше (soft skills)

До чого тут документація? Загалом кожний вищенаведений пункт можна задокументувати. І це стосується не тільки тестової документації. QA-інженер як найближчий «родич» end-users бере участь у всіх процесах. Наприклад, обговорили ризики — записали в Requirement specification, а згодом у Test plan; роз’яснили Use cases — описали Test Cases document, внесли правки в сам Use case document; спланували тести на User stories — внесли правки в документ User stories; вийшли в production — уточнили User guide, Wiki, Tutorials...

Очевидно, що робота тестувальника — це не тільки тестування, а й хороша документація.

Переписати проєкт чи розібратися через документи

Як часто трапляються ситуації, коли потрібно переписати проєкт? Може, не часто. Та в мене були такі ситуації.

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

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

Отже, щоб «щось» переписати, потрібно вивчити проєкт досконало і знати кожну його деталь, мати чіткий план дій, всі вимоги, передбачувані проблеми тощо. Технічна документація повинна існувати не тільки на словах. Документація здатна допомогти в перспективі. Навіть якщо потрібно переписати частину проєкту в майбутньому.

Що я пропоную (замість висновку)

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

Командна робота передбачена у всьому: від планування до кінцевих user guides. QA-інженер має колосальний вплив на процес розробки технічної документації. Команда тестування — найближча до кінцевого користувача. Ні замовник, ні менеджери не можуть так сильно зрозуміти «біль» та «радість» від користування продуктом, який розробляє ваша команда. Тому тестувальникам не завадить мати більше контролю над документацією.

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

👍НравитсяПонравилось4
В избранноеВ избранном5
Подписаться на автора
LinkedIn

Похожие статьи




Підписуйтесь: SoundCloud | Google Podcast | YouTube


30 комментариев

Подписаться на комментарииОтписаться от комментариев Комментарии могут оставлять только пользователи с подтвержденными аккаунтами.

«Очевидно, що робота тестувальника — це не тільки тестування, а й хороша документація.»
Вот из-за таких предложений и появляется плохая документация, хотите сократить расходы не пишите вообще но не навешивайте дополнительные задачи на не профильных специалистов ибо будет то о чём все пишут «документация от которой толку почти нет».
Каждая проектная роль ведет ту документацию которая нужна в пределах её работы.
1) Бизнес аналитик и ПМ ведут документацию — о проектных процессах, роад мапах на заданный период и входящих требованиях к проекту
2) Разработчики — о архитектурных решениях, документацию кода описывающую поведение методов, классов, модулей, апи (в большинстве случаев она авто генерируемая)
3) Тестировщики — ведут тестовую документацию (тест планы, тест кейсы, чек листы)
4) Тех. писатели — ведут пользовательскую документацию в том числе и для саппорт команды
5) Девопс инженеры — ведут документацию о инфраструктуре, базах данных, конфигах и железе на котором все вертится
В таком случае все хорошо и работает как надо, а если сваливать все в одну кучу и пытаться поддерживать централизовано для всех то получается свалка в которой ничего не найдешь и большинство документов уже не актуально.
А искать виноватого и прикрываться документацией или её отсутствием в случае каких то ошибок или недопониманий, срывов сроков это вообще нонсенс, для этого существуют риски и их оценка при планировании тех или иных действий и задача любого руководителя на каждой проектной роли их учитывать.

Все вірно, документація — це командна робота, а не одного відділу тестування.
Кожний відділ описує те, в чому розуміється.

Я пропоную розібрати роботу тестувальника. Тестувальник не лише тестує, а «втручається» в процеси планування, розробки тощо. Це не означає, що він відповідальний за все. Це означає, що має свою точку зору, своє бачення. І дуже часто це бачення варте документування (внесення змін в якусь фічу чи таск, наприклад).

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

Висловлю не дуже популярну думку: я б не радив зловживати документацією, адже це дорого і рідко ефективно.

Як на мене документ є сенс писати, якщо зрозуміло хто його буде читати, зрозуміло навіщо, і зрозуміло, що читати таки буде.

Все решта дуже швидко старіє.

Звісно, є якісь базові речі, аля into, де що лежить, як запустити, коментарі в неочевидних місцях ... але, це доречі, як раз і відповідає озвученому критерію.

І, в цілому, варто зауважити, що писати чи не писати є сенс обговорювати щодо кожного конкретного документу в кожному конкретному проекті.

В кожного документу мусить бути визначена аудиторія. Поводимося як з сегментом Споживача — визначаємо, що йому потрібно :)

Не могу понять людей, которые считают, что документация не нужна.
Типа, тебе устно объяснили один раз — и ты уже всё знаешь и будешь помнить всегда.
Распространенность отсутствия документации поражает воображение.

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

Согласна, но всё же мне кажется, что любая документация лучше её отсутствия, т.к. её существование уже стимулирует её поддерживать :) Да и просить \ требовать обновить документацию проще, чем создавать её с нуля (на мой взгляд)
Решения у меня нет. Я data scientist, а не разработчик, а в работе с данными отсутствие документации распространено ещё больше. В моей команде мы только недавно начали относиться к этому более системно (после моего продолжительного нудения на эту тему). Пока у нас такой подход, посмотрим, будет ли это работать:
— время на документацию выделено в расписании как еженедельный митинг, чтобы никто на это время не посягал, и одновременно чтобы не было отмазок, что я не успел
— есть примеры \ подходы как документировать таски в джире и страницы в вики
— документация в вики выделяется как один из пунктов DoD таски
— регулярное ревью документации другими членами команды

Есть 2 вопроса.
Первый — процессуальный. QA — подтверждает сроки, Разраб — планирует релизы и сроки разработки. Ок, допустим, что это даже реально. Но если не попадем в сроки — кто несет ответственность? QA плохо подтвердили или разработчики фигово релиз спланировали?

Второй уже по документации. Я не нашел (возможно невнимательно прочитал) информации о гарантии соответствии документации реальному положению дел. Как быть уверенным, что то, что описанно в документации ещё не устарело и не выпилино из проекта?

Как быть уверенным, что то, что описанно в документации ещё не устарело и не выпилино из проекта?

в общем случае — никак.
все зависит от того кто пишет, ведет документацию и его коммуникации с разработчиками, если он не разработчик.

то есть — от людей.
а люди — самый ненадежный элемент в разработке ПО.
просто — единственный, так что — никаких гарантий. ни в чем :)

Если вы пускаете написание документации на самотек (надеетесь, что нужные люди в нужный момент по своей инициативе внесут информацию в вики, или куда там вы ее вносите) — то да, вы абсолютно правы

Если вы пускаете написание документации на самотек

ну ок, вы не пускаете, и засучив рукава проверяете
код на соответствие документации и наоборот.

не мне напоминать CTO что
если вы не доверяете работнику — то этого работника надо увольнять, а не «контролировать» чего он там понаделал.
или приставить к нему контролирующего. в надежде что этому хоть можно доверять :D

Интересная мысль. Я правильно понимаю, что QA/QC процессы, код ревью, логи ошибок, трекинг действий пользователей — это все тоже от недоверия? И у «правильного» руководителя их нет, т.к. он свято верит всем сотрудникам, а сотрудники — биороботы и не ошибаются.

как вы гарантируете что описанные процессы и мероприятия — выполняются, а не просто заполняются отчеты, формы, и радостно сдаются?

не часто, но слышал и такое, когда дев отдел и QA вступают в сговор, чтобы — всем премию получить.

как вы гарантируете что нет сговора?

сотрудники — биороботы и не ошибаются.

ну и я о том.
у вас — биороботы что-ли, все просто берут инструкцию, чек лист, и тупо=точно ее выполяют.

а про

код ревью

у меня давно шутка
Самое сложное в ревьюве пул реквеста, проревьювать строчки кода которых нет, но которые должны были быть обязательно.

Извините, я не понимаю вас. Можете дать прямой ответ: QA/QC — это от недоверия или все же необходимый процесс?

Извините, я не понимаю вас. Можете дать прямой ответ: QA/QC

я тоже вас не понимаю.

Я вам про провода, которые могут быть оборваны, а вы мне
так что, законы Максвелла врут что-ли об электромагнетизме?

какие гарантии дают законы Максвелла что провода целы?

необходимый процесс

как гарантируете что этот процесс — выполняется людьми которые обязаны его выполнять?
лично проверяете результаты?

Если вы хотите получить консультацию — это в личных сообщениях :)

Если хотите похвастаться своими процессами — хвастайтесь, мне будет интересно прочитать. Я вполне допускаю, что вы гараздо опытнее и я смогу подчерпнуть новое.

Если хотите сказать, что из-за того, что нет гарантий, то и перечисленные мной процессы не нужны — то так и скажите прямо. У меня вопрос был лишь об этом. Переучивать или переубеждать вас — не моя цель.

Если вы хотите получить консультацию — это в личных сообщениях :)

не хочу. в peopleware гарантий быть не может.
если вы уверены что у вас процессы гарантируют(или существуют такие) — то это проблемы ваших иллюзий.

Я вполне допускаю, что вы гараздо опытнее и я смогу подчерпнуть новое.

а от иллюзий не отказываются в споре без «драки» :)

Если хотите сказать, что из-за того, что нет гарантий, то и перечисленные мной процессы не нужны

и не думал такого говорить.

процессы, ритуалы — их необходимость, уже видны даже в стае более менее умственно развитых животных.

они появятся даже тогда, в коллективной работе, когда их никто вообще не создавал.

У меня вопрос был лишь об этом

тогда ок, процессы есть всегда и везде
только они не гарантируют что им следуют, кроме случая когда это биороботы.

так что раз не применяются автоматизиваронные средства контроля соотвествия кода документации
никаких гарантий.

В первом вопросе — функциональная ошибка. QA подверждает сроки — это как? С каких это полномочий, а, будучи честным, в меру какой ответственности и общего видения проекта? Сроки определаются коммандой, ответственный проект-менеджер отвечает за этот процесс. Хотите получить реальный результат — задействуйте реальные ресурсы ;)

По второму вопросу — гарантии Вам может дать лишь SLA, при тщательной его проработке.

Документация, как и продукт — постоянно устаревают. Как и все МЫ, без исключений.
Устаревшие данные должны очищатся по мере релизов, но это в идеале.

Стает вопрос — что именно, какую ценность для Вас может принести документация в рамках контракта? Это сложный. но важный вопрос, предупреждаю

Документування — робота не тільки інженера з якості. Документувати ідеї, основні бажані характеристики (а це ще не вимоги), візію, ROI-стратегію ітепе мусить Замовник, документувати decision log під час підписання контракту — Sales/Pre-sales, архітектурне бачення — архітектор чи техлід, і так далі. Що вже лишилось незадокументоване — бізнес-аналітик. НЕ техрайтер.
Сталось так, що наша команда аналітиків спеціалізується саме на документуванні багатомільйонного рішення, цілісної системи (паралельно з розробкою нових фіч) — і Замовник чітко це розуміє, тримає команду аналітиків виключно під цю задачу ;)

Так, документування — це робота всієї команди, від Замовника до Support команди.

Лиш без чіткої задачі, поставленої Лідером, або ж Замовником — це виконуватися не буде. Точніше буде, але зрозумілої та цілісної бази знань ніхто не отримає. Бо це — задача на роки ;)
А спеціалістів по впорядкуванні бази знань — не так багато ;)

Максимум документации, которую видел за время работы — настройка энвайромента либо описания процесса релиза

Приходи работать в кровавые энтерпрайзы и увидишь опечатанные шкафы для хранения журналов учетов изменений в журналах учетов об изменениях в документации.

Спасибо, как-то не тянет туда :)

Що я бачив на практиці, а я люблю бути легко замінним, то намагаюся все, що можливо документувати:
— В проекті з автоматизації тестування, як правило вистачає Readme.md в корені, це дається почитати і спробувати інсталювати проект новим спіробітникам, якщо вони знаходять застарілі місця, то вони переписуються.
— Для входження в специфіку проекту пишуться «Knowledge sharing» документ, який теж оновлюється при приході нової людини.
— Якщо треба описувати, щось більш високорівневе, напр, чому у нас таке, а не інше рішення, то вистачає свого підрозділа в корпоративній вікі.
— Ну, а таски і фічі документуються в чомусь джироподібному.
Так тестувальник реально може це все перевірити на придатність до тестування, вибачте за тавтологію.
— аджайл нажаль в силу своєї специфіки і швидкозмінності вимагає дуже багато спілкування з усіма. Це і є живо ходяча документація. Головне потім записати результати обговорень.

Але кожного разу, стикнувшись з проблемою, можна було «полистати» попередні обговорення. Зазвичай 80% вже мали рішення та були задокументовані кілька місяців тому. Так, про них просто забули чи не звернули на них уваги. А коли настала черга конкретного розгляду питання чи навіть розробки — виявилося, у команди вже є рішення!

Щось це схоже на відсутність product owner та technical lead. Кожен з двох мав би бачити картину в цілому, пам’ятати минулі проблеми, та бути доступним для запитань команди. Натомість програмісти витрачають (оплачуваний) час для пошуку поточних питань в купі старих документів.

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

Документация — не серебряная пуля, после низко квалифицированной команды не спасет от факапов.
ИМХО были проекты без документации и качественным кодом.
И ДА, такое реально (!). Только очень и очень редко :)

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

Подписаться на комментарии