Skip to main content

Технічна документація

Навіщо документувати?​

Обов'язок кожного технічного спеціаліста документувати свою роботу і т.д.

Details
  1. Без неї немає продукту
  2. Тестувальнику
  3. Інфо для опису продукту, його фішок та переваг
  4. Колегам по розробці
  5. Для делегування задач
  6. Для оцінки та ревю що зроблено
  7. Клієнтам
  8. Для версійної разрабоки
  9. Критерій якості продукту. при незалежній експертизі спитають
  10. для правильного та ефективного використання і взагалі це красиво)

Розміщення в проекті GIT​

DOCS                        # документація
├── admin/docs              # документація admin    
├── dev/docs                # документація розробника та API 
├── user/docs               # документація користувача окрема папка 

├── docs                    # документація користувача - 1 папка 
│   ├── index.md            # стартова сторінка документації
├── mkdocs.uml
├── openapi.yaml            # може генеруватись автоматично з postman
├── postman.json            # може генеруватись автоматично з openapi
readme.md                   # опис проекту
changlog.md                 # change log
💡 Tip

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

  • /docs/ - доступ до інструкції
  • /docs/api - доступ до опису API

або через окремий субдомен docs.name чи apidocs.name

Види технічної документації​

Основною мовоую для документації є мова Markdown, скорочено MD. API зберігаються у форматі OpenAPI/Swagger або в форматі Postman

  • Markdown - основні команди markdown
  • Dev - документація розробника: Vue, API, Function, Helper
  • DB-ERD - опис таблиць та функцій БД
  • MkDocs - SSG - для генерації документацій
  • Docosaur - SSG для інструкція користувача
  • OpenAPI - форматі OpenAPI Swagger та Postman
  • JSDoc - документація коду
  • git - правила commit, mr тощо, version
  • changelog - опис версій і змін
  • readme - опис проекту
  • package.json - meta проекту
  • unit-test - тести

документація є частиною GIT проекту або як окремий проект(и) документації

💡 Tip

Документацію, test пишуть Розробники та QA Для автоматизації вигрузки схеми бази, api використовуйте api

Порядок​

  1. Створюємо dev документація з user story
  2. unit test по user story успішні/не успішні сценарії
  3. Ведемо changelog, readme

Види проектної документації​

  • ТВ/TR - вимоги та user story
  • Протоколи
  • Bug Report
  • Звіт
  • Методика тестування

Корисні посилання​