Как стать автором
Обновить
24.31
Рейтинг

Подготовка технической документации *

Всё о деятельности технических писателей

Сначала показывать
  • Новые
  • Лучшие
Порог рейтинга
  • Все
  • ≥0
  • ≥10
  • ≥25
  • ≥50
  • ≥100

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

Разработка веб-сайтов *Управление проектами *Подготовка технической документации *
Tutorial

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

Читать далее
Всего голосов 2: ↑1 и ↓1 0
Просмотры 1.6K
Комментарии 2

Docs-as-code: DevOps-технологии в документировании, или Как подружить технического писателя и разработчика

Блог компании Цифра Управление разработкой *Подготовка технической документации *

Привет, Хабр! Меня зовут Роман Блинов, я ведущий технический писатель в «Цифре» — в команде по развитию платформы ZIIoT. Этот пост будет о подходе Docs-as-code для документирования разработки ПО. Пишу с прицелом на тех читателей (то есть писателей), кто этот подход пока не пробовал и по факту имеет набор файлов в Confluence, файлы формата .docx и .pdf, на поддержку, обновление и оформление которых тратится порядка 70 % времени (а хотелось бы меньше), и 101 отговорку разработчиков, чтобы не участвовать в документировании.

Сначала расскажу, с какими проблемами сталкиваются писатели до перехода на Docs-as-code, затем опишу подход в общих чертах и в конце упомяну об основной трудности его внедрения по собственному опыту и опыту коллег.

Читать далее
Всего голосов 3: ↑3 и ↓0 +3
Просмотры 2.5K
Комментарии 24

Гайд по User Stories для Junior BA / PO / PM

Анализ и проектирование систем *Подготовка технической документации *
Из песочницы

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

Читать далее
Всего голосов 6: ↑6 и ↓0 +6
Просмотры 5.3K
Комментарии 6

Плагин IDEA Mind Map для Intellij IDEA

Программирование *Подготовка технической документации *
Tutorial

При работе в разных компаниях, чаще всего встречалось раздражающее отсутствие актуальной документации или «документационная мусорная куча», где было сложно найти требуемое. Нередко проблемы были в стиле «это знал уволившийся Петя, но его не спросить». Или в наличии деталей, которые были незначимы по мнению разработчика, но которые оказывались критическим знанием «переоткрываемым» последователями (нередко и самим разработчиком, вернувшемуся к проекту). Для облегчения жизни, был сделан специальный инструмент, позволяющий держать записи по проекту прямо среди исходных текстов.


Читать дальше →
Всего голосов 31: ↑31 и ↓0 +31
Просмотры 11K
Комментарии 20

Метод персон против Франкенштейна: эликсир продакта для бизнес анализа

Блог компании Лига Ставок Анализ и проектирование систем *Управление продуктом *Карьера в IT-индустрии Подготовка технической документации *

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

Можно встретить много  примеров того как применять customer development, который опирается на “персоны”,  для B2C, B2B продуктов, даже для B2BC решений, но сегмент продуктов внутреннего потребления как правило скрыт от посторонних взглядов. Их чаще называют проектами по “автоматизации бизнес-процессов”, которые решают задачу для внутреннего клиента. Особенностью таких проектов/продуктов является секретность, неотвратимость пользования создаваемым продуктом (как считают многие оптимизаторы) и возможность “дотянуться” до потребителя рукой.

В статье аккумулированы некоторые типичные ситуации, выстраданные многолетней практикой по автоматизации бизнес-процессов в десятке отраслей, где я побывал на разных ролях: от business analyst до product manager. Ключевый объект суммирирования опыта — люди, а именно знаниях об их осознанных или неосознанных потребностях, которые являются отправной точкой улучшений.

Читать далее
Всего голосов 4: ↑3 и ↓1 +2
Просмотры 1K
Комментарии 0

«Предъявите паспорт» или добавляем поля «должность» и «цветовая схема» в профиль пользователя XWiki

CMS *Подготовка технической документации *
Tutorial

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

В этот раз мы рванем сразу с места в карьер и попробуем расширить профиль пользователя в Xwiki.

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

Читать далее
Всего голосов 5: ↑5 и ↓0 +5
Просмотры 1.1K
Комментарии 1

Российские BIM-технологии: разработка технологических схем в Model Studio CS

Блог компании Нанософт CAD/CAM *Промышленное программирование *Подготовка технической документации *

Эта статья продолжает цикл публикаций о российских BIM-технологиях и посвящена программному комплексу Model Studio CS Технологические схемы, предназначенному для решения задач разработки схемных решений при проектировании разделов ТХ.

Введение

На первый взгляд разработка схемных разделов технологических решений может показаться простой и довольно тривиальной задачей. Результат в виде получившейся схемы всегда представляется простым и понятным. Но когда понимаешь, что внесенная информация и решения, принятые на этом этапе, проходят через все стадии проекта, становится ясно – для эффективной работы и сокращения числа возможных ошибок необходим удобный и надежный инструмент. Инструмент, который автоматизирует стандартные операции и позволит не отвлекаться от процесса проектирования. Такой, каким в полной мере является программный комплекс Model Studio CS Технологические схемы.

Читать далее
Всего голосов 8: ↑8 и ↓0 +8
Просмотры 968
Комментарии 0

Генерация документации с использованием JSDoc

Разработка веб-сайтов *JavaScript *Подготовка технической документации *
Tutorial

JSDoc - это язык разметки, используемый для аннотирования исходного кода JavaScript с использованием комментариев. Аннотации обрабатывается различными инструментами для создания документации в доступных форматах, таких как HTML и Rich Text Format.

Читать далее
Всего голосов 10: ↑9 и ↓1 +8
Просмотры 4.3K
Комментарии 6

Как мы автоматизировали процесс генерации Release Notes

Блог компании МТС API *Управление разработкой *DevOps *Подготовка технической документации *

Всем привет! Меня зовут Семен. Я Java-разработчик и руководитель группы Java-разработки в Центре Big Data компании MTS Digital. В этом посте я хочу поговорить о Release Notes. Что это такое, почему не стоит писать их вручную и какие есть способы автоматизации. Покажу и реальный пример того, как организована  работа с Release Notes в нашем проекте.

Читать далее
Всего голосов 15: ↑14 и ↓1 +13
Просмотры 4.2K
Комментарии 9

Как закалялась документация

Блог компании Юнидата Управление продуктом *Подготовка технической документации *

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

Хочу очертить тот путь, который мы прошли, и рассказать о том, какие решения принимали, и что из этого вырастало.

Читать далее
Всего голосов 7: ↑7 и ↓0 +7
Просмотры 2.8K
Комментарии 12

Какая документация нужна вашему проекту и кто должен её писать

Блог компании Ozon Tech Управление разработкой *Управление проектами *Управление продуктом *Подготовка технической документации *

Привет! Меня зовут Катя, я руководитель команды технических писателей в Ozon.

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

Разбираемся в вопросе
Всего голосов 20: ↑18 и ↓2 +16
Просмотры 5K
Комментарии 3

Использование диаграммы классов UML при проектировании и документировании программного обеспечения

Проектирование и рефакторинг *UML Design *Подготовка технической документации *
Tutorial

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

Читать далее
Всего голосов 5: ↑5 и ↓0 +5
Просмотры 3.9K
Комментарии 1

“Тайный клуб системной аналитики” или путь к идеалу

Блог компании Банк «Открытие» Анализ и проектирование систем *Управление разработкой *Управление персоналом *Подготовка технической документации *

Hello World!

Меня зовут Сергей Павлов, я тимлид по системной аналитике в банке "Открытие” на продукте МСБ “Бизнес-Портал”. Хочу рассказать, как я решал задачи по управлению командой, когда к ней присоединился.

Скажу сразу: тут я не буду описывать графики, капасити, велосити и любые инструменты, связанные с командными метриками. Речь пойдет именно об организации процессов для повышения качества взаимодействия при коллективной работе.

Итак, морозное утро, вежливый голос руководителя мне говорит: “Это команда системных аналитиков, начинай творить добро”. Я смог выдавить только “угу” и сел думать насчет того самого творить и того самого добра.

Читать далее про добро
Всего голосов 4: ↑4 и ↓0 +4
Просмотры 3K
Комментарии 6

Кто такой DocOps-инженер

Блог компании YADRO Карьера в IT-индустрии DevOps *Подготовка технической документации *
Из песочницы

Привет! Меня зовут Наталья и я DocOps-инженер в компании Yadro.

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

Немного о себе

Я окончила механико-математический факультет, во время учёбы занималась матмоделированием в области авиастроения, затем семь лет работала инженером по локализации и техническим писателем в Xsolla, потом полтора года в роли руководителя команды автоматизации, и вот я DocOps в компании Yadro.

Читать далее
Всего голосов 10: ↑8 и ↓2 +6
Просмотры 3.4K
Комментарии 5

Пошаговая инструкция как использовать MkDocs для создания сайта с документацией продукта

Блог компании Ростелеком Open source *DIY или Сделай сам Подготовка технической документации *
Tutorial

Всем привет! Мы продолжаем разбирать наши решения. Сегодня расскажем о том, как, используя генератор Material for MkDocs, можно создать несложный, но удобный статический сайт с документацией (и не только!).

А ещё как встроить его в CI/CD для автосборки и автопубликации (мы используем Gitlab CI, о чём подробно рассказывалось в предыдущем туториале), а также как использовать плагины к генератору чтобы, к примеру, создавался не только сайт, но и его pdf-представление.

Добро пожаловать под кат!

Читать далее
Всего голосов 5: ↑5 и ↓0 +5
Просмотры 2.5K
Комментарии 10

Как (не) нужно строить базу знаний для проекта с нуля. Часть Первая, утопическая

Блог компании RUVDS.com Анализ и проектирование систем *Управление разработкой *Управление продуктом *Подготовка технической документации *
Tutorial
image

Сентябрь 2020 года. В этот момент, моей Суперучилке (имя вымышленное), платформе по поиску репетиторов в США, требуется срочно новая команда поддержки, потому что старая не справляется с бизнес-логикой и создает проблемы. А для новой команды нужна новая база знаний, чтобы обучить новичков с учетом ошибок ветеранов.

В октябре начинался новый сезон и приходили новые клиенты. Собеседовать и обучить новую команду надо позарез за неделю до сезона, чтобы успеть потренироваться. У меня есть три недели, и часики уже тикают. И все происходит в условиях качелей между удаленкой и офисом: собеседовал новичков я вживую, а учились мы уже в Google Meet.  

Тут мой воспаленный мозг начал шевелиться. В июле как раз выстрелила моя статья о Zettekasten, методе ведения личной базы знаний для работы и творчества. Я уже полтора месяца сидел в сообществе Zettelkasten и проникался прелестями ассоциативных, нелинейных и экзотичных баз знаний. Мне за советом в телеграм пишут каждый день, и я добросовестно прокрастинирую, отвечая на вопросы.
Давай, приключение на 15 минут, туда и обратно!
Всего голосов 30: ↑30 и ↓0 +30
Просмотры 9.2K
Комментарии 5

Документирование кодовой базы. Зачем и как?

C++ *Подготовка технической документации *
Tutorial

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

Читать далее
Всего голосов 6: ↑5 и ↓1 +4
Просмотры 5.4K
Комментарии 15

Техническая документация и Agile: совместить несовместимое

Блог компании Orion Innovation XML *Usability *Agile *Подготовка технической документации *

Привет, меня зовут Татьяна, я — старший технический писатель в Центре разработки Orion Innovation. Недавно нам пришлось переводить в Agile крупный проект. Несколько Scrum-команд разработчиков, довольно обширный стэк документов, многие из которых устарели просто потому, что в каскадной разработке писатели не успевали их обновлять. Служба поддержки завалена жалобами от пользователей: «Но у вас же так написано, почему не работает?»

Сразу спойлер: интеграция техписов в Agile прошла успешно, хоть и не всегда гладко. Благодаря этому опыту, мы выработали несколько рекомендаций, которыми хочу поделиться.

Читать далее
Всего голосов 6: ↑6 и ↓0 +6
Просмотры 4K
Комментарии 4

Юзер-стори идеальная, а багов 100500? Как мы тестируем документацию

Блог компании Test IT Тестирование IT-систем *Тестирование веб-сервисов *Тестирование мобильных приложений *Подготовка технической документации *

Представьте, в требованиях ошибка или документация составлена криво. Требование уходит в разработку, программист неверно его истолкует и реализует фичу с искаженной функциональностью. Если это заметит тестировщик, отправит баг-репорт. И это ещё хороший сценарий! В реальной жизни не все баги исправляют с первого раза, а порой они попадают в прод с печальными последствиями. Как мы тестируем документацию — в продолжении.

Читать далее
Всего голосов 6: ↑6 и ↓0 +6
Просмотры 8.4K
Комментарии 0

Вклад авторов