Всё о деятельности технических писателей
Хабр, привет! На связи коллективный разум технических писателей компании «Базис». Над представленным в этой статье проектом мы работали вместе, так что и рассказывать о нем будем вместе. Если точнее, расскажем о том, как познавали методологию Docs-as-Code, зачем техническим писателям дружить с DevOps-инженерами, а главное, почему мы перешли от reStructuredText к AsciiDoc и что нам это принесло.
Большинство гайдов по программному обеспечению написаны трагически плохо.
В них не хватает важной информации, и это мешает пользователям повторить описанные в руководстве процессы. Иногда автор исходит из скрытых предпосылок, которые не соответствуют ожиданиям читателя.
Но есть и хорошая новость: научиться писать грамотные руководства проще, чем вы думаете. Следуйте нескольким простым правилам, и ваши тексты будут выделяться на фоне повсеместной посредственности.
Привет! Меня зовут Павел Астахов, я работаю в департаменте системного анализа SM Lab. Сегодня расскажу про проектировочную документацию и её стандартизацию в нашей компании.
Причины внедрения стандартизации
Причина 1. Сотрудники
Департамент системного анализа появился в 2020 году: на тот момент нас было 50 человек в 20 командах; к 2024 году мы сильно разрослись и нас стало уже 260 системных аналитиков, которые трудились в 85 командах. Рост и увеличение масштаба департамента выявили проблемы, которые ранее не были видны и постепенно стали выходить на первый план.
Хочу поведать свою историю, как большая нагрузка, множество рутинной работы и постоянное отвлечение меня от основной работы, разработки архитектуры софта, толкнули меня на создание системы, которая бы автоматизировала ряд процессов в пресейле новых проектов. Что позволило мне сэкономить в итоге много времени и сил.
Всем привет!
Сегодня хочу затронуть холиварную тему: как сделать диаграмму BPMN немного читабельнее и как избежать логических ошибок. Мы рассмотрим несколько «проблемных» BPMN‑диаграмм, с которыми я встречался в своей практике, и узнаем, как их можно улучшить.
Приветствую, дорогие читатели. В этой статье хочу поделиться множеством «вредных советов», которые покажутся не только забавными, но и крайне полезными для начинающих аналитиков и технических писателей. Эти советы основаны на личном опыте и на опыте коллег в начале карьерного пути. Надеюсь, что мои размышления помогут вам избежать этих ошибок.
Было ли когда-то у вас желание получить документацию к своему проекту в пару кликов?
У меня — регулярно. Жила была проблема, которая преследует меня с начала жизни — я понятия не имею, что происходит и зачем тут написано так много букв которые делают какие-то умные штуки. И я не только про код, с квантовой физикой да и с жизнью в целом такая же проблема.
Мы отправляемся на крупнейший в России глинозёмный комбинат. Здесь из бокситов получают глинозём - важный сырьевой компонент для производства алюминия. Это место, где промышленность соединяет науку и технологии, превращая сырьё в основу для будущего высокотехнологичных изделий.
Отсканированные PDF-файлы, которые невозможно редактировать, знакомы многим. Документ выглядит как текст, но это всего лишь изображение, и любое изменение становится настоящей головной болью. На помощь приходит OCR — технология оптического распознавания символов.
Посмотрев назад на свой длинный путь в бизнесе, могу смело заявить, что я знаю о бизнес-процессах больше, чем кто-либо.
Руководя своей командой, я заметил, что мы тратим массу времени на повторяющиеся вопросы и одни и те же проблемы. «Как оформлять счета?», «Какая процедура работы с клиентами?», «Что делать, если клиент недоволен?» — эти вопросы повторялись просто каждый день. Даже очевидные задачи превращались в постоянные созвоны и обсуждения. Это тормозило развитие бизнеса, мешало внедрять автоматизацию и вызывало у сотрудников демотивацию к работе.
Так я пришел к идее: нужно структурировать всё. С того момента я написал более 1400 регламентов, охватывающих почти все бизнес-процессы, и это стало настоящей революцией в нашей работе. В этой статье я хочу поделиться, как мне удалось создать систему, которая избавила нас от хаоса, и объясню, почему инструкции — это не формальность, а основа для успеха.
Привет! Меня зовут Лиза, я технический писатель в ЕДИНОМ ЦУПИС. В этой статье хочу поделиться с вами инструментарием технических писателей. Многие думают, что мы просто пишем в текстовых редакторах, но на самом деле набор инструментов для создания технической документации может быть сильно шире.
Для коллег других специальностей этот набор приоткроет доселе невиданные сферы, которые технические писатели могут охватить помимо создания текстов. А для самих техписателей ознакомиться с этим списком будет интересно и полезно, чтобы порефлексировать: вот это я тоже умею, а вот тут знаю инструмент получше, а это неплохо бы освоить. Так что присаживайтесь поудобнее и давайте окунемся в почти безграничный мир инструментов технических писателей!
В эпоху цифровизации техническая документация меняет свои формы и функции. Печатные издания, когда-то считавшиеся основным источником информации, постепенно уступают место онлайн-форматам. Однако остаётся вопрос: есть ли будущее у печатных документов, или их неизбежно ждёт забвение? В этой статье мы разберём преимущества и недостатки обоих форматов, а также рассмотрим современные инструменты, которые помогают создавать качественную и удобную документацию.
Всем привет! Меня зовут Мария Ибрагимова, я технический писатель в X5 Tech. Но так было не всегда. Ещё каких-то 4 года назад я работала в проектном институте с устрашающим названием ЛЕННИИХИММАШ и не представляла себя в сфере информационных технологий. Хочу поделиться своим опытом, как мне удалось подойти к IT.
Ведь если история изменений пишется, значит, это кому-нибудь нужно!
Привет! Я Арина, работаю техническим писателем в IT и люблю заниматься текстами, которые, кажется, редко кому нравятся: текстами об изменениях в продукте (What's New, Release Notes и всякими подобными ченджлогами). И я твердо убеждена, что такие тексты, во-первых, читают, а во-вторых, через них можно и нужно нести реальную пользу. Эта статья о том, как писать для тех, кто вас реально читает.
Не так давно, мне пришел вопрос от подписчика, ответ на который превратился аж в небольшую статью :)
> Руслан, привет!) а подскажи пож-та, может есть у тебя ссылочки на
шаблоны/примеры/лучшие практики по документированию архитектуры и инфраструктуры системы
Вопросы документирования и особенно актуальности документации — на мой взгляд, одни из самых больных в нашей с вами айтишечке. Но, если дело касается сущностей, которые мы можем описать кодом (или как код) — всё становится сильно проще.
Представьте: вы — успешная IT-компания с крутыми проектами и серьезными клиентами. Вас знают в профессиональной среде, но за её пределами — тишина. Единственные медиаактивности — статья в «Клерке» и несколько постов в Telegram-канале. А ведь за цифрами и фактами стоит команда, которая решает сложнейшие задачи и запускает амбициозные проекты.
Делимся конкретными приемами, чтобы вашу статью точно сохранили.
Привет, на связи Марина и Катя (@lieutkat) — технические писатели Cloud.ru. За четыре года наша команда составила больше 30 правил по написанию технической документации и… прочувствовала на себе весь масштаб усилий на проверку и запоминание получившейся редакционной политики.
Год назад мы решили автоматизировать проверку этих правил. В статье расскажем, что из этого вышло, какие шишки мы набили по пути, а также детально рассмотрим линтер Vale, который стал нашей палочкой-выручалочкой.
«Технический писатель» — это не просто человек, который документирует то, что уже знают все остальные. Это креативный инженер, к которому идут за пониманием, а не просто за инструкциями. Разберём главные мифы о профессии и покажем, что на самом деле скрывается за этими двумя словами.
Недавно я в очередной раз прочитал на Хабре, что списки — это один из признаков текста, созданного нейросетью. Значит меня можно считать «нейросетью» устаревшей модели, выпущенной ещё в 70-х годах XX века. Я начал составлять списки в детстве, почти сразу, как только научился писать.
Я очень люблю списки: они позволяют легко и в то же время наглядно структурировать информацию. По эффективности списки находятся где-то между обычным текстом, в котором объекты перечисляются в строке через запятую, и таблицей, которая по сути является двухмерным списком. Взгляд читателя легко скользит по номерам или маркерам списка. Можно быстро оценить количество строк, понять их последовательность и структуру, перейти к нужной строке.
В этой статье я хочу поделиться с вами своими правилами оформления списков.
Воркшоп — это не просто демонстрация, но и своего рода экзамен перед заказчиком. Как бы хорошо ни было продумано и протестировано новое решение, на демонстрации всегда может случиться что-то неожиданное и непредвиденное. Воркшоп чем-то похож на прямой эфир на телевидении. Все участники готовятся к эфиру заранее, много раз прогоняют сценарий, репетируют сложные моменты.
В статье расскажу о том, как строится весь процесс, о технических сложностях и закулисье...