Это первая статья в корпоративном блоге компании documentat.io. Мы занимаемся заказной разработкой технической документации и помогаем компаниям настраивать процессы документирования.

Многие разработчики сталкиваются с тем, что писать и поддерживать документацию трудно: непонятно с чего начать, что и куда написать, и как это безобразие дополнять по мере развития проекта. Часто в результате получается документация, которую тяжело читать. А значит пользователи читать её и не будут, вместо этого будут действовать методом проб и ошибок или дёргать техподдержку. И это в лучшем случае. В худшем — откажутся от использования продукта. В итоге пострадают все: и разработчики, и пользователи, и техподдержка, и бизнес.

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

Введение

Я — системный аналитик, и моя работа заключается в том, чтобы проектировать автоматизированные информационные системы. Впрочем, нет, она заключается в том, чтобы писать и писать документы. Третий раз слово «писать» повторять не буду — все-таки, не «Илиада». Но занудность формы чем-то определенно роднит проектную документацию с древнегреческой поэмой, особенно если речь идет о работе с государственным заказчиком.

Диаграммы — глоток творчества в этом море текста. О диаграммах и пойдет речь в данной статье. Если точнее — о PlantUML — с моей точки зрения, наиболее адекватном инструменте их создания на текущий момент.

Мировая статистика говорит, что английским владеет примерно 1,4 миллиарда человек, но носителей среди них всего 380 миллионов. То есть статистически семь из десяти читателей англоязычной документации — не носители языка.

Если мы хотим, чтобы наша английская документация хорошо выполняла свою функцию — эффективно доносила знания о продукте до читателя — мы должны предъявить к ней уникальное требование, которое обычно не предъявляем к документации на русском:

Документация должна быть написана так, чтобы даже тот, кто плохо знает язык, мог ей воспользоваться.

В этой статье поговорим о приёмах, которые помогут сделать вашу англоязычную документацию понятной даже для читателей, слабо владеющих английским.

Хабр, привет! В прошлых статьях про UML (Часть 1, Часть 2) мы узнали что такое язык моделирования UML и зачем он нужен, а также рассмотрели диаграмму классов и диаграмму компонентов. Сегодня я хочу продолжить тему проектирования процессов и остановиться на диаграмме объектов.

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

Хабр, привет! Меня зовут Витя, я работаю системным аналитиком, сегодня хочу рассказать про такой обязательный навык аналитиков, как проектирование процессов. Думаю, что каждый, кто будет работать на позиции системного/бизнес аналитика, рано или поздно столкнется с такой задачей.

1. Обоснование необходимости ТЗ

Отправная точка — требования

Хочу пирожное, потом морожное!
Вовка в тридевятом царстве

Введение

Так уж вышло, что в течение своей деятельности мне немало доводилось работать с публичными API, причем как в со стороны, которая их предоставляет, так и со стороны, которая интегрируется. И здесь я хочу рассказать не только про один из кейсов, который решал ранее, но и поделиться результатами проводимого анализа, полученным опытом, а также набитыми шишками.

Материала вышло многовато, поэтому разбил его на 2 части. В части 1 (этой статье) рассмотрим, почему и зачем вообще публичным API нужна документация, есть ли у нее какие-то отличия от документации внутренних API, а также проанализируем и детально разберем различные подходы к ведению такой документации, попутно познакомившись поближе с полезными инструментами.

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

Привет! Меня зовут Андрей Гладилин, я работаю в Swordfish Security над составлением технической документации для ИТ-решений. Завершая  предыдущую статью, мы обсудили преимущества и недостатки DocOps-подхода к разработке технической документации и немного поговорили о прикладной реализации этой парадигмы — Doc-as-code.

Позволю себе напомнить, что основная идея DocOps заключается в том, что создание технической документации осуществляется в тесном контакте с разработкой программного продукта и во многом «отзеркаливает» этапы последней — рабочие процессы максимально синхронизируются и объединяются в общую систему, широко применяется автоматизация рутинных операций и упрощается совместная работа, что позволяет повысить общую эффективность процесса.

Теперь перейдем к практической реализации DocOps-решения, которое мы начали обсуждать в первой части статьи.

Содержание

• Вопросы и ответы
  
• Введение
  
  • Пре-реквизиты
    
  • Настройка компьютера
    
  
  
• 1.0 Играем с Busybox
  
  • 1.1 Docker Run
    
  • 1.2 Терминология
    
  
  
• 2.0 Веб-приложения и Докер
  
  • 2.1 Статические сайты
    
  • 2.2 Образы
    
  • 2.3 Наш первый образ
    
  • 2.4 Dockerfile
    
  • 2.5 Docker на AWS
    
  
  
• 3.0 Многоконтейнерные окружения
  
  • 3.1 SF Food Trucks
    
  • 3.2 Сети Docker
    
  • 3.3 Docker Compose
    
  • 3.4 AWS Elastic Container Service
    
  
  
• 4.0 Заключение
  
  • 4.1 Следующие шаги
    
  • 4.2 Фидбек автору
    

Вопросы и ответы

Что такое Докер?

Определение Докера в Википедии звучит так:

программное обеспечение для автоматизации развёртывания и управления приложениями в среде виртуализации на уровне операционной системы; позволяет «упаковать» приложение со всем его окружением и зависимостями в контейнер, а также предоставляет среду по управлению контейнерами.

Ого! Как много информации.

Плагины VS Code, без которых техническим писателям и разработчикам документации жить можно, но сложно. В подборке — линтеры, форматирование, работа с git, проектирование API, подготовка схем и милота для удобной разработки.

Привет! Меня зовут Андрей Гладилин, я работаю в Swordfish Security над составлением технической документации для ИТ-решений. Нравится нам это или нет, но она сопровождает каждый этап разработки и эксплуатации ПО. Работая над десятками и сотнями описаний ежедневно, я отметил ряд особенностей и сделал полезные выводы. И здесь постарался разобрать все ключевые аспекты, влияющие на качество технической документации, и дать практические рекомендации по его повышению. Этот материал поможет техническим писателям, менеджерам и разработчикам создать документацию, которая точно будет работать.