Всё о деятельности технических писателей
Приветствую, дорогие читатели. В этой статье хочу поделиться множеством «вредных советов», которые покажутся не только забавными, но и крайне полезными для начинающих аналитиков и технических писателей. Эти советы основаны на личном опыте и на опыте коллег в начале карьерного пути. Надеюсь, что мои размышления помогут вам избежать этих ошибок.
Было ли когда-то у вас желание получить документацию к своему проекту в пару кликов?
У меня — регулярно. Жила была проблема, которая преследует меня с начала жизни — я понятия не имею, что происходит и зачем тут написано так много букв которые делают какие-то умные штуки. И я не только про код, с квантовой физикой да и с жизнью в целом такая же проблема.
Мы отправляемся на крупнейший в России глинозёмный комбинат. Здесь из бокситов получают глинозём - важный сырьевой компонент для производства алюминия. Это место, где промышленность соединяет науку и технологии, превращая сырьё в основу для будущего высокотехнологичных изделий.
Отсканированные PDF-файлы, которые невозможно редактировать, знакомы многим. Документ выглядит как текст, но это всего лишь изображение, и любое изменение становится настоящей головной болью. На помощь приходит OCR — технология оптического распознавания символов.
Посмотрев назад на свой длинный путь в бизнесе, могу смело заявить, что я знаю о бизнес-процессах больше, чем кто-либо.
Руководя своей командой, я заметил, что мы тратим массу времени на повторяющиеся вопросы и одни и те же проблемы. «Как оформлять счета?», «Какая процедура работы с клиентами?», «Что делать, если клиент недоволен?» — эти вопросы повторялись просто каждый день. Даже очевидные задачи превращались в постоянные созвоны и обсуждения. Это тормозило развитие бизнеса, мешало внедрять автоматизацию и вызывало у сотрудников демотивацию к работе.
Так я пришел к идее: нужно структурировать всё. С того момента я написал более 1400 регламентов, охватывающих почти все бизнес-процессы, и это стало настоящей революцией в нашей работе. В этой статье я хочу поделиться, как мне удалось создать систему, которая избавила нас от хаоса, и объясню, почему инструкции — это не формальность, а основа для успеха.
Привет! Меня зовут Лиза, я технический писатель в ЕДИНОМ ЦУПИС. В этой статье хочу поделиться с вами инструментарием технических писателей. Многие думают, что мы просто пишем в текстовых редакторах, но на самом деле набор инструментов для создания технической документации может быть сильно шире.
Для коллег других специальностей этот набор приоткроет доселе невиданные сферы, которые технические писатели могут охватить помимо создания текстов. А для самих техписателей ознакомиться с этим списком будет интересно и полезно, чтобы порефлексировать: вот это я тоже умею, а вот тут знаю инструмент получше, а это неплохо бы освоить. Так что присаживайтесь поудобнее и давайте окунемся в почти безграничный мир инструментов технических писателей!
В эпоху цифровизации техническая документация меняет свои формы и функции. Печатные издания, когда-то считавшиеся основным источником информации, постепенно уступают место онлайн-форматам. Однако остаётся вопрос: есть ли будущее у печатных документов, или их неизбежно ждёт забвение? В этой статье мы разберём преимущества и недостатки обоих форматов, а также рассмотрим современные инструменты, которые помогают создавать качественную и удобную документацию.
Всем привет! Меня зовут Мария Ибрагимова, я технический писатель в X5 Tech. Но так было не всегда. Ещё каких-то 4 года назад я работала в проектном институте с устрашающим названием ЛЕННИИХИММАШ и не представляла себя в сфере информационных технологий. Хочу поделиться своим опытом, как мне удалось подойти к IT.
Ведь если история изменений пишется, значит, это кому-нибудь нужно!
Привет! Я Арина, работаю техническим писателем в IT и люблю заниматься текстами, которые, кажется, редко кому нравятся: текстами об изменениях в продукте (What's New, Release Notes и всякими подобными ченджлогами). И я твердо убеждена, что такие тексты, во-первых, читают, а во-вторых, через них можно и нужно нести реальную пользу. Эта статья о том, как писать для тех, кто вас реально читает.
Не так давно, мне пришел вопрос от подписчика, ответ на который превратился аж в небольшую статью :)
> Руслан, привет!) а подскажи пож-та, может есть у тебя ссылочки на
шаблоны/примеры/лучшие практики по документированию архитектуры и инфраструктуры системы
Вопросы документирования и особенно актуальности документации — на мой взгляд, одни из самых больных в нашей с вами айтишечке. Но, если дело касается сущностей, которые мы можем описать кодом (или как код) — всё становится сильно проще.
Представьте: вы — успешная IT-компания с крутыми проектами и серьезными клиентами. Вас знают в профессиональной среде, но за её пределами — тишина. Единственные медиаактивности — статья в «Клерке» и несколько постов в Telegram-канале. А ведь за цифрами и фактами стоит команда, которая решает сложнейшие задачи и запускает амбициозные проекты.
Делимся конкретными приемами, чтобы вашу статью точно сохранили.
Привет, на связи Марина и Катя (@lieutkat) — технические писатели Cloud.ru. За четыре года наша команда составила больше 30 правил по написанию технической документации и… прочувствовала на себе весь масштаб усилий на проверку и запоминание получившейся редакционной политики.
Год назад мы решили автоматизировать проверку этих правил. В статье расскажем, что из этого вышло, какие шишки мы набили по пути, а также детально рассмотрим линтер Vale, который стал нашей палочкой-выручалочкой.
«Технический писатель» — это не просто человек, который документирует то, что уже знают все остальные. Это креативный инженер, к которому идут за пониманием, а не просто за инструкциями. Разберём главные мифы о профессии и покажем, что на самом деле скрывается за этими двумя словами.
Недавно я в очередной раз прочитал на Хабре, что списки — это один из признаков текста, созданного нейросетью. Значит меня можно считать «нейросетью» устаревшей модели, выпущенной ещё в 70-х годах XX века. Я начал составлять списки в детстве, почти сразу, как только научился писать.
Я очень люблю списки: они позволяют легко и в то же время наглядно структурировать информацию. По эффективности списки находятся где-то между обычным текстом, в котором объекты перечисляются в строке через запятую, и таблицей, которая по сути является двухмерным списком. Взгляд читателя легко скользит по номерам или маркерам списка. Можно быстро оценить количество строк, понять их последовательность и структуру, перейти к нужной строке.
В этой статье я хочу поделиться с вами своими правилами оформления списков.
Воркшоп — это не просто демонстрация, но и своего рода экзамен перед заказчиком. Как бы хорошо ни было продумано и протестировано новое решение, на демонстрации всегда может случиться что-то неожиданное и непредвиденное. Воркшоп чем-то похож на прямой эфир на телевидении. Все участники готовятся к эфиру заранее, много раз прогоняют сценарий, репетируют сложные моменты.
В статье расскажу о том, как строится весь процесс, о технических сложностях и закулисье...
Как эффективно организовать процесс обмена знаниями в компании, минимизировать потерю времени и повысить продуктивность команды. В статье делимся проверенными инструментами и подходами из личного опыта техписов, которые сделали взаимодействие внутри команды удобным и результативным.
С вами Семён Факторович и компания documentat.io. Продолжаю делиться результатами большого соцопроса среди техписателей, который мы проводили в начале 2024 года.
В этой части поговорим об инструментарии: какой самый распространённый инструмент ведения документации в России? Получилось ли импортозаместить Confluence? Что популярнее — Markdown или Asciidoc? Сколько российских техписателей работают в парадигме Docs as Code?
«Возьми вишневый мамин плащ и кружку молока» – вспомнился мне фрагмент моего любимого стиха из книги Григория Остера «Вредные советы». И я понял, что у меня для вас тоже есть пара советов. Конечно, мои советы не такие «сочные», но все же использовать их стоит с умом и большой осмотрительностью.
Мы рассмотрим три приема работы с XWiki, которые скорее всего выбиваются из хорошей практики, но могут быть полезны в ваших экспериментах. В любом случае, если вы пересели с иглы Confluence на его open source аналог (со слов разработчиков). То вам, точно не помешает знать о возможностях доработки его напильником.
Начнем мы с получения доступа к командной оболочке прямо из XWiki, а закончим обхождением ограничений CORS с помощью скрипта на Python.
Как говорится: «Милости прошу под кат»
Запутались в выборе платформы для работы с документацией? Функций море, терминология запутанная, а вариантов столько, что глаза разбегаются—даже опытные специалисты порой теряются! Мы собрали для вас 10 ключевых критериев, которые помогут найти идеальную систему управления документацией без лишней головной боли. Давайте разберёмся вместе!
Когда говорят о требованиях, первое, что приходит в голову: «О, опять список хотелок!» На самом деле, это запросы, идеи и проблемы, которые стейкхолдеры (то есть все те, кого заденет ваш проект) выдают разработчикам, аналитикам и менеджерам. Это может быть как организация в целом, так и один несчастный человек: от директора до сотрудника, который просто хочет, чтобы его жизнь стала немного проще.
Например, директор хочет знать, чем занимались его сотрудники в месяц. Менеджеры хотят, чтобы у них был инструмент контроля, а пользователи хотят, чтобы этот инструмент не превратил их жизнь в бюрократический кошмар.