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

    

      Усім з дитинства знайоме радянське гасло Маяковського: «Без бумажки ти букашка…, а з документом — ти ЛЮДИНА !!!»

 

 

   

     Теж цей вислів чудово пасує і до розробки програмного забезпечення: «Без належної документації, Ви ризикуєте розробити — відносно придатне до вжитку програмне забезпечення із купою багів.»

 

 

 

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

 

 

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

     Але ж існують великі проекти, у структурі яких без документації, просто нереально зорієнтуватися! Неначе без дорожньої карти у абсолютно незнайомому просторі. Нерідко, те що ти маєш накодити, виділяють кольоровим маркером на 100-тій сторінці Технічного Завдання. А що роблять інші учасники проекту на 20-тій чи 260-тій — годі й уявити!

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

А що ж узагалі представляє собою програмна документація — Software Documentation?

   Доволі ясну, чітку і стислу відповідь пропоную самостійно переглянути Вікіпедії. Зрозуміло майже…

Але яка суттєва різниця між Проектною документацією, Технічним Завданням і Технічною документацією?

     Проектна документація —  описує програмний продукт, як правило, у загальних рисах. Які патерни застосовуватимуться. Як конструюватимуться класи. Чому структура даних організована саме таким чином, а не інакше. Часто даються вказівки, як згодом слід модернізувати програму.

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

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

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

   Технічну Документацію зручно складати за допомогою спеціальних сервісів генераторів документації: (Doxygen, NDoc, Javadoc, Visual Expert,  EiffelStudio, Sandcastle, ROBODoc, POD, TwinText, Universal Report ін.) Генератори документації дуже зручно допомагають постійно підтримувати документацію в актуальному стані. Ці інструменти витягують коментарі із коду. За потреби зміст можна редагувати. Плюс їх можна ще використовувати при збірках програми.  

      Отже, Технічна Документація є складовою частиною вихідного коду. Файл README помічали? Це воно!

    Також Технічна документація може бути сформована у текстові довідкові посібники до друку, кому як зручно.

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

     Створює Технічну документацію програміст. Technical Writer формалізує її до «дружньої» форми. Завдання тестера відповідно протестувати-звірити на кожному етапі процесу тестування чи програма виконує задеклароване у Технічній Документації. З хорошою документацією тестеру тестувати досить легко і приємно. Такий підхід, як мінімум, запевняє у максимальному тестовому покритті проекту.

Загалом принципи до створення Технічної Документації ті ж самі що й до коментування коду:

  • чіткість,
  • структурованість,
  • логічність,
  • однозначність,
  • зрозумілість,
  • стислість,
  • повнота вмісту інформації.

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

     Усі текстові документи укладаються за міжнародними стандартами ISO переважно охоплюються стандартом ICS 01.110, кодові хто як хоче, але гарно би було у форматах: (DITA), DocBook, S1000D.

Хороша для користувача Технічна Документація складається з:

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

Підсумок:

     Ми розглянули щойно ідеальний варіант картини. У житті не завжди так. Все ж радимо Вам писати технічну документацію до усіх проектів, власних проектів, до проектів у портфоліо і навіть навчальних проектів. Траплялося бачити на Git – хабі профілі, де усе ідеально красиво оформлене. Скажу. Одразу таке позитивне враження складається. Оу-у-у!

Related posts

Leave a Comment

Цей сайт використовує Akismet для зменшення спаму. Дізнайтеся, як обробляються ваші дані коментарів.