Pull to refresh
6
0
Андрей Гладилин @agladilin

Технический писатель

Send message

Весь Росатом работал на Джире — и что случилось в день Х

Reading time10 min
Views125K
image

В 2018–2019 году мы уже догадывались, что нужно какое-то импортозамещение, потому что как-то немного странно, что Росатом зависит от зарубежного вендора. Джира проникала в структуру незаметно и понемногу, и в какой-то момент оказалось, что на ней ведутся многие проекты кроме строительства АЭС и других объектов. И речь не про ИТ-проекты, а вообще про все проекты, которые у нас есть.

Пару лет мы лежали в сторону поиска аналога (которого на самом деле нет).

1 февраля 2021 году Atlassian объявил о прекращении поддержки серверной версии. Решили запланировать переезд в дата-центр, но увидели, что это такой хитрый способ поднять цену в полтора раза. Стало грустно, но аналогов на рынке всё ещё не было.

Потом был технический сбой на 2 недели. Люди за 2 недели потеряли свои данные. Стало ещё грустнее.

Потом пришло письмо счастья, что аккаунты РФ будут отключены. Но сроки не обозначили.

В общем, мы опять огляделись в поисках аналогов для проектов нашего масштаба, взяли решения нескольких вендоров для сравнения, чуть не сошли с ума от прекрасных стратегий их продажи и доработок продуктов прямо во время презентаций, плюнули и написали своё отраслевое решение. Которое ещё и предлагаем другим российским компаниям.
Читать дальше →
Total votes 270: ↑249 and ↓21+284
Comments323

Diátaxis: структура технической документации

Reading time9 min
Views4.8K

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

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

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

Читайте в статье
Total votes 8: ↑8 and ↓0+8
Comments5

PlantUML — все, что нужно бизнес-аналитику для создания диаграмм в программной документации

Reading time11 min
Views95K

Введение


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


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

Читать дальше →
Total votes 33: ↑33 and ↓0+33
Comments51

Как улучшить английский в документации. Часть 3: мировая аудитория

Reading time8 min
Views2.4K

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

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

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

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

Читать далее
Total votes 14: ↑13 and ↓1+15
Comments4

UML: обзор основных типов диаграмм, диаграмма объектов. Часть 3

Reading time3 min
Views7.5K

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

Читать далее
Total votes 7: ↑5 and ↓2+6
Comments3

UML: обзор основных типов диаграмм, диаграмма компонентов. Часть 2

Reading time4 min
Views29K

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

Читать далее
Total votes 3: ↑2 and ↓1+2
Comments2

UML: обзор основных типов диаграмм, диаграмма Классов. Часть 1

Reading time7 min
Views42K

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

Читать далее
Total votes 8: ↑7 and ↓1+8
Comments6

Техническое задание на сайт

Reading time11 min
Views698K
UPD: Продолжение статьи с примером техзадания

Не так давно на хабре были две статьи (Согласно техническому заданию и А зачем мне ТЗ? Я и так знаю!) посвященные техническим заданиям. У меня обе статьи вызвали, мягко говоря, недоумение, в особенности статья «Согласно техническому заданию». На мой взгляд, это вообще вредная статья, которая приводит к неверному понимаю сути ТЗ. В связи с этим хочу выразить свой взгляд на этот вопрос. Не буду говорить обо всех тех. заданиях, слишком широка тема, но думаю смогу рассказать о ТЗ на сайт.

То описание технического задания, о котором речь пойдет ниже, не является пересказом ГОСТа, но скорее является его творческой переработкой, хорошо сдобренной горьким опытом. Описанный ниже подход к ТЗ не охватывает все аспекты сайтостроения, но задает общее направление.

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

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


А зачем вообще нужно ТЗ на сайт? Заказчик говорит: «Нужен следующий сайт: каталог товаров, корзина, форма заказа, доставка, мы на карте, о нас, обратная связь». Что не ясно? Ничего необычного, всё обыденно и рутинно.

Разработчик отчетливо представляет, что нужно сделать, а сделать, в его понимании нужно вот так:



Далее много букв
Total votes 212: ↑209 and ↓3+206
Comments141

Ликбез по техническому заданию

Reading time7 min
Views81K
Польза: получите знания о том, что такое ТЗ и как его составить. Обогатите словарный запас словами: концептуальная модель, data flow, mind card, user flow. use cases, wireframes, ER-model, client-server, API.

Для кого: начинающим разработчикам и желающим чтобы их поняли (заказчикам, стартапам и менеджерам).

Время чтения: 7 минут.

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

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

Существует распространенное заблуждение, что достаточно сказать: “Нужно приложение для музея/кошки/завода” и сразу станет понятно, что вам необходимо.
Total votes 5: ↑3 and ↓2+3
Comments11

Разработка Технического задания по ГОСТ 34 легко и просто

Reading time45 min
Views312K
Нередко слышишь мнение, что составление Технического задания по ГОСТ 34 (ТЗ) занятие не только трудоемкое, но и крайне раздражающее, поскольку приходится писать много всякой ерунды, воды. Но подумайте: разработкой этого ГОСТа занимались целые НИИ, это был проект на государственном уровне, обобщен опыт сотен проектов автоматизации, сложных проектов. Неужели они могли написать чушь?

На самом деле, при грамотном подходе ГОСТ очень сильно помогает не только при разработке ТЗ, но и в ходе реализации проекта автоматизации в целом (и не только в госконтрактах, но и для коммерческой разработки). Грамотные люди его писали. Но чтобы воспользоваться плодами их трудов, нужно немного понять замысел не только ТЗ, но и ГОСТ 34 в целом.

В данной статье мы пункт за пунктом разберем все требования ГОСТа и попробуем сделать разработку ТЗ по ГОСТ 34 не обременением, а большой помощью в проекте.
Читать дальше →
Total votes 28: ↑27 and ↓1+26
Comments21

Удобная памятка и 8 ссылок на документацию по ГОСТ 34 (автоматизированные системы)

Reading time2 min
Views35K
Одним пятничным вечером несколько лет назад я получил задание от руководителя подготовить за выходные ТЗ на конкурс. Видимо, я слишком уж излучал радость от предстоящих выходных, и боссу просто было приятно занять их чем-то новым и интересным, как он считал – ведь до этого с техническими документами мне работать не доводилось. Сейчас уже не смогу припомнить, какая там была система, но точно какой-то мониторинг. Субботнее утро принесло разочарование. Миллионы ссылок, сотни статей одна другой информативнее. От одной аббревиатуры ГОСТ веяло скукой и пылью. Примерно так и началось мое знакомство с семейством ГОСТ 34 на автоматизированные системы. Под катом удобная памятка по этому самому ГОСТу, которая совершенно случайно когда-то повстречалась на просторах сети и помогла систематизировать данные в знатном ворохе документов.

gost_1.png
Окунуться в ГОСТ и вынырнуть
Total votes 14: ↑11 and ↓3+8
Comments23

Стандарты и шаблоны для ТЗ на разработку ПО

Reading time7 min
Views766K

Введение


Недавно ко мне обратились, чтобы я посоветовал стандарты для написания технического задания (ТЗ) на разработку автоматизированных систем (АС) и программного обеспечения (ПО). Вот думаю, сейчас зайду в Яндекс, найду подходящую статейку и отправлю её. Но не тут-то было! Одной статьи, где перечисляются стандарты для ТЗ, включая шаблоны и примеры готовых документов, я не нашел. Придется сделать такую статейку самому…

И так, основные стандарты, методологии и своды знаний, где упоминается ТЗ или SRS (Software (or System) Requirements Specification):

• ГОСТ 34
• ГОСТ 19
• IEEE STD 830-1998
• ISO/IEC/ IEEE 29148-2011
• RUP
• SWEBOK, BABOK и пр.
Читать дальше →
Total votes 36: ↑34 and ↓2+32
Comments22

Как документировать публичные API для продукта. Большой гайд, часть 1

Level of difficultyMedium
Reading time17 min
Views16K

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

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

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

Читать далее
Total votes 7: ↑6 and ↓1+5
Comments4

Как разработать техническую документацию, которая точно будет работать. Часть 2. DocOps в действии

Reading time28 min
Views6.5K

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

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

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

Что же, начнем!
Total votes 8: ↑8 and ↓0+8
Comments14

Полное практическое руководство по Docker: с нуля до кластера на AWS

Reading time39 min
Views1.6M



Содержание



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


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


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


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



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

Читать дальше →
Total votes 125: ↑124 and ↓1+123
Comments44

28 расширений VS Code для разработки документации

Reading time3 min
Views26K

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

Читать дальше
Total votes 13: ↑9 and ↓4+7
Comments40

Как создать техническую документацию, которая точно будет работать

Reading time12 min
Views14K

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

Читать далее
Total votes 6: ↑3 and ↓30
Comments2

Information

Rating
Does not participate
Works in
Registered
Activity

Specialization

Technical Writer
English
Git
HTML
CSS
Dita
Technical translation
Markdown
Writing instructions
Russian language
Static Site Generators