Как стать автором
Обновить
61.47

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

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

Сначала показывать
Порог рейтинга
Уровень сложности

Варианты усиления фальшпола для ЦОД

Уровень сложностиПростой
Время на прочтение8 мин
Количество просмотров622

Современные потребности в Центрах Обработки Данных достигли невероятных масштабов, превратив их проектирование и строительство в практически рутинный процесс. Каждый заказчик стремится получить больше, чем просто стандартное решение: им нужны ЦОД, которые соответствуют принципу «Больше, выше сильнее». Больше машзалов, выше потолки, мощнее охлаждение. Иногда эти запросы доходят до экзотических решений, таких как размещение ЦОД в регионах с холодным климатом, например, в Скандинавии, где естественная вечная мерзлота используется для охлаждения серверов, или даже подводные дата-центры, которые погружаются на дно океана для снижения затрат на охлаждение.

Однако, несмотря на такие необычные подходы, большинство проектов ЦОД остаются довольно типичными. Тем не менее, каждый из них имеет свои уникальные особенности и нюансы, которые возникают из-за классической дилеммы: «Быстрее, лучше, дешевле — выбери только два». При разработке проекта часто приходится выбирать между тем или иным решением, обосновывая свою позицию экономией средств или большей надежностью. Эта проблема становится ключевой при разработке любого проекта, заставляя инженеров и архитекторов постоянно искать компромиссы. Например, приходится выбирать между более дорогим, но надежным оборудованием и бюджетными решениями, которые могут сэкономить средства, но потребуют дополнительных усилий для обеспечения стабильной работы. Каждый выбор требует тщательного обоснования, будь то экономия ресурсов или повышение надежности инфраструктуры.

Читать далее

Новости

Как писать Release Notes, чтобы их читал и бизнес, и разработчики

Уровень сложностиПростой
Время на прочтение9 мин
Количество просмотров952

Привет, Хабр! Меня зовут Иван Арискин, я занимаюсь развитием продукта «Единый адрес» в HFLabs. Поскольку компания сравнительно небольшая, иногда приходится самостоятельно писать и редактировать Release Notes (RN). Они же — новости продуктов, или changelog. За одни меня благодарили, за другие — троллили, но я научился смещать баланс в сторону положительных реакций. 

В статье разберу, что и зачем писать в Release Notes и как заинтересовать бизнес техническими обновлениями. Пригодится всем, кто ведет документацию по продукту и хочет, чтобы она приносила реальную пользу. 

Читать далее

Use Case: как описывать эффективные сценарии использования. Part 1

Уровень сложностиПростой
Время на прочтение5 мин
Количество просмотров2K

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

Пользовательский путь закладывается на этапе работы с требованиями. И, помимо UX/UI, важным этапом проработки является формирование сценариев использования системы. В этой статье разберем теоретическую часть и определим, что же такое Сценарий использования.

Читать далее

Текст без опечаток в документации и не только: внедряем CSpell

Уровень сложностиСредний
Время на прочтение26 мин
Количество просмотров2K

В статье приведен обзор возможностей спеллчекера CSpell, а также проанализированы сложности, с которыми я столкнулся при адаптации этого инструмента для работы с нашей документацией в парадигме Docs as Code.

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

Помимо работы в командной строке, в статье рассматриваются примеры прекоммитных проверок и интеграции с VS Code.

Читать далее

Continuous Documentation, MVD и документация как продукт: три подхода, которые изменят ваше представление о документации

Уровень сложностиПростой
Время на прочтение11 мин
Количество просмотров1.1K

Когда-то я относился к документации по-старому: написал – и забыл. Думаю, многие разработчики меня поймут. Традиционный подход зачастую сводится к тому, что документацию пишут в конце проекта или от случая к случаю, а затем она покрывается пылью. В эпоху Agile и DevOps такой подход не работает: изменения в коде происходят постоянно, и статичные тексты не успевают за ними. В результате документация стремительно устаревает, вводя команду в заблуждение и порождая ошибки​. Настала пора пересмотреть взгляд на эту часть разработки.

Хочу поделиться тремя подходами, которые кардинально изменили мой подход к документации. Это Continuous Documentation (непрерывная документация), MVD (Minimum Viable Documentation) – минимально жизнеспособная документация, и «документация как продукт». Каждый из них появился как ответ на боль, с которой мы сталкивались в гибкой разработке: как держать документацию актуальной, достаточной и полезной для пользователей. Расскажу о каждом по порядку – на примерах из собственного опыта, с живыми кейсами и свежими идеями. Возможно, эти подходы перевернут и ваше представление о том, какой должна быть документация в современных проектах.

Читать далее

Интеграция виджета обратного звонка МТС Exolve в документацию на MkDocs

Время на прочтение8 мин
Количество просмотров398

Привет, Хабр! Это Екатерина Саяпина, Product Owner платформы МТС Exolve. Сегодня покажу, как быстро добавить виджет обратного звонка на страницу, созданную с помощью MkDocs — статического генератора сайтов с уклоном в техническую документацию. Такое размещение виджета бывает нужно в справочных разделах сложных продуктов, где клиентам может потребоваться консультация или разъяснение каких-то технических моментов.

Для большей конкретики возьмем страницу с описанием S3 API вымышленного облачного провайдера — это типичный сценарий, где пользователю может потребоваться быстрая консультация специалиста.

Читать далее

«Клюква» — автоматизация документации проектов на Python

Уровень сложностиПростой
Время на прочтение7 мин
Количество просмотров3.9K

Привет!

Меня зовут Алексей Фоменко. Я разработчик из Нижнего Новгорода.

Сегодня хочу рассказать вам о своем сервисе «Клюква».

«Развесистая клюква» или просто «Клюква» в общем виде означает ложные или искаженные представления о чем‑либо.

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

Читать далее

Как создаются шедевры: будни технического писателя

Уровень сложностиПростой
Время на прочтение6 мин
Количество просмотров1.4K

Один из важнейших принципов работы команды «Оптимакрос» — прозрачность. Нам важно, чтобы каждый процесс был понятным и хорошо документированным, чтобы даже новичок быстро разобрался. За созданием такой понятной документации стоят технические писатели. Елена Логунова, технический писатель «Оптимакрос», рассказывает, как превращает сложные технические решения в простые инструкции, без которых невозможна ни прозрачность процессов, ни удобное использование продукта.

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

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

Читать далее

AI в работе технического писателя

Уровень сложностиСредний
Время на прочтение4 мин
Количество просмотров1.7K

Всем привет! Меня зовут Севара Ахтямова и я работаю техническим писателем – аналитиком около 4 лет. В этой статье я расскажу, как AI помог мне справиться с рабочей рутиной — от генерации toctree до отладки сборки Sphinx-документации. Всё это — на реальных задачах. Я постаралась собрать побольше примеров из личного опыта. Надеюсь, не слишком много.

Читать далее

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

Уровень сложностиПростой
Время на прочтение12 мин
Количество просмотров4.8K

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

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

Читать далее

Почему я использую doc-as-a-code

Уровень сложностиСредний
Время на прочтение12 мин
Количество просмотров12K

В этой статье я постараюсь рассказать и показать, почему я использую подход doc-as-a-code, как помогает git системному аналитику и зачем это всё.

Читать далее

Станция «Confluence». Перевезти всё, что нажито непосильным трудом

Уровень сложностиПростой
Время на прочтение10 мин
Количество просмотров4.4K

Меня зовут Дина, я занимаюсь аналитикой в одной из команд «Ростелеком Информационные Технологии» (РТК ИТ). В статье хочу осмыслить полученный опыт переноса документации и поделиться своими соображениями. Возможно вы тоже думаете о переходе на базу знаний. Такой переход может занять больше времени, чем ожидается. Я расскажу, как это было у нас. В конце подведу итоги: что получили и что потеряли.

Читать далее

Нейросетевой переводчик в командной строке, или Приручаем API Ollama и OpenWebUI

Уровень сложностиСредний
Время на прочтение12 мин
Количество просмотров2.2K

Связку из Ollama и OpenWebUI я использую больше года, и она является моим рабочим инструментом в части работы с документацией и контентом и по-настоящему ускорила работу по локализации документации HOSTKEY на другие языки. Но жажда исследований не отпускает, и с появлением относительно вменяемой документации к API у OpenWebUI возникло желание написать что-то, автоматизирующее работу. Например, перевод документации из командной строки.

Читать далее

Ближайшие события

Почему мы построили монолит на чистой архитектуре. И почему это взбесило системных аналитиков

Уровень сложностиСредний
Время на прочтение12 мин
Количество просмотров18K

Привет! Меня зовут Павел Лукьянов, я заместитель CTO в AGIMA. На одной из прошлых работ мы с ребятами попробовали внедрить так называемую чистую архитектуру на монолитном проекте. И это был интригующий опыт. Во-первых, мы начали намного рациональнее подходить к оценке задач. Во-вторых, заметно сократили time-to-market. А в-третьих, сильно разозлили наших аналитиков. Считаю, такими впечатляющими результатами стоит делиться.

Читать далее

Как аналитику на «чиле» пройти испытательный срок

Уровень сложностиПростой
Время на прочтение10 мин
Количество просмотров4.4K

Расширенный чек-лист онбординга.

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

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

Когда я получил свой первый подобный документ, этот пункт тоже не вызвал во мне подозрений. Но я не знал, что список доступов в чек-листе был уже [немного] уставший, и актуальные сервисы и способы получения доступов прописаны в другом документе, которые мне выдал наставник только после того, как я его об этом спросил.

Успешно пройти испытательный срок

Грейды бизнес и системных аналитиков

Время на прочтение13 мин
Количество просмотров11K

Скиллы и компетенции аналитиков в данной статье описаны в срезе компании, занимающейся аутсорс‑разработкой. Это накладывает определенные требования к аналитикам, так как им за частую приходится участвовать в проектах с разными стеками технологий и доменами. Что в свою очередь требует широкой эрудиции и умения быстро разбираться в новых предметных областях и технологиях. Ниже приведены требования к каждому грейду для бизнес‑аналитиков (BA) и системных аналитиков (SA), с акцентом на их отличия. Учтены ключевые компетенции (SQL, Python, бизнес и системный анализ, UML, BPMN, интеграции, брокеры сообщений, микросервисная архитектура, базы данных), софт скиллы (усиливаются с ростом грейда), опыт работы (основной фактор грейда) и требования, продиктованные аутсорсинговой спецификой.

Читать далее

Шаблоны проектирования в документации

Время на прочтение5 мин
Количество просмотров4.4K

В моей предыдущей статье Запахи технической документации я писала про схожесть применяемых способах познания программирования по отношению к документации. Что я сделаю сейчас? Совершенно то же самое. Напомню, что шаблоны проектирования описывают типичные способы решения часто встречающихся проблем при проектировании программ. Рассмотрим шаблоны проектирования, представленные на ресурсе Refactoring Guru (сейчас он запрещен на территории РФ). Ну, что, начнем?

Читать далее

Принципы кодирования объектов капитального строительства

Время на прочтение23 мин
Количество просмотров822

Авторы: Бобов Д., Красильников Н.

Оглавление

Введение.

Исходные принципы построения кода.

Лексическая структура кода и допустимые символы.

Группа 3. Кодирование функциональных, строительных подсистем или зон.

Кодирование помещений.

Группа 4. Кодирование агрегатов.

Особенности нумерации агрегатов.

Пример кодирования агрегата.

Группа 2. Код здания, сооружения или территории.

Группа 1. Код местоположения и площадки объекта (site, plant).

Правила кодирования инфраструктурных сетей.

Правила кодирования автодорог и других инфраструктурных путей.

Правила кодирования распределённых технологических систем (расположенных в разных зданиях или сооружениях, но представляющих единую систему)

Кодирование Работ.

Кодирование Документов.

Иерархическое представление закодированных позиций.

Рекомендации по маркировке закодированных позиций.

Заключение.

Читать далее

Большой опрос о технической документации и о тех, кто её разрабатывает — 2025

Время на прочтение3 мин
Количество просмотров573

Уже второй год подряд мы (documentat.io) проводим опрос среди русскоязычных технических писателей. 

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

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

Читать далее

Новый стайлгайд для технических писателей Ozon Tech: шаги, описания разделов и выводы

Уровень сложностиПростой
Время на прочтение7 мин
Количество просмотров3.6K

Привет! Меня зовут Аня Салугина, я технический писатель в Ozon Tech. Наша команда готовит и актуализирует документацию для покупателей, продавцов, партнёров, разработчиков и сотрудников Ozon. Недавно мы решили, что хотим улучшить наш стайлгайд и сделать его публичным.

Эта статья о том, как мы это сделали: искали новую структуру, обсуждали спорные моменты с командой и запускали обновлённый стайлгайд в работу.

Спойлер: командная работа — ключ к успеху.

Читать далее
1
23 ...