Всё о деятельности технических писателей
При составлении контрактов, технических заданий, проектов термины становятся юридически значимыми определяющими условиями. В текущих условиях, когда требования ст. 46 184-ФЗ «О техническом регулировании», ГОСТы являются уже не добровольной, а обязательной нормой. Возникает необходимость использовать и сопоставлять тысячи терминов. Для облегчения работы с этими понятиями и создан этот словарь.
Почему инжиниринговые компании предпочитают работать в специализированных решениях для ведения технического документооборота и комплексного управления проектами? На что стоит обратить внимание при выборе подходящего инструмента и как построить системное управление, которое очень высоко ценится в проектном менеджменте, повышая доверие заказчиков и подрядчиков? Компания ООО «Аквапрув» поделилась своим опытом эффективного управления проектами в строительстве в среде TDMS Фарватер.
Участие в ВТО потребовало стандартизации терминов и определений, для: «предупреждения действий, вводящих в заблуждение приобретателей, в том числе потребителей» (ст. 6, 46 184-ФЗ). Общепринятая двухуровневая система разделения на обязательные техрегламенты и добровольные ГОСТы становится одноуровневой после требований ст.46 184-ФЗ, при создании описаний и в контрактах на поставку и, соответственно, для используемых терминов и интерпретации их определений. В данном словаре представлены десятки тысяч определений, чтобы эффективнее реализовывать различные задачи в IT отрасли.
Наша команда Mobile Doc&Loc «Лаборатории Касперского» занимается подготовкой документации и локализации B2C-продуктов компании для мобильных устройств. Основная сложность (и одновременно фишка) нашей работы заключается в том, что необходимо регулярно подготавливать переводы на 34 языка в крайне сжатые сроки.
Меня зовут Юлиана Соломатина, я — Doc&Loc-инженер, и в этой статье я расскажу про инструменты-автоматизации, которые помогают нам справляться с наплывом задач и укладываться в дедлайны, не жертвуя при этом качеством. Кстати, многие из этих инструментов мы разработали сами.
Привет, Хабр! Я Евгения Береснева, технический писатель в X5 Tech, и я считаю, что классный раздел вопрос-ответов нужен любому продукту. В статье как раз расскажу о том, как его создать.
По мере увеличения кодовой базы любая компания начинает испытывать потребность в упорядочивании разрозненной документации, иными словами — создании собственной «базы знаний». О чём стоит помнить при выборе конкретных инструментов и как сделать их одинаково удобными для разработчиков и техписателей, попробуем разобраться в сегодняшней статье.
Хотела начать текст с шутки про то, что раз инструкции никто не читает, то и писать их не обязательно. Однако 14 лет работы в IT-сфере доказывают, что это всё же довольно глупая шутка. В современных компаниях (не только в IT, но и особенно в IT!) на документации завязаны практически все процессы от проектирования ПО и ведения бэклога до эксплуатации и поддержки пользователей. Люди со стороны часто не догадываются, что в командах кроме суровых разработчиков, дотошных тестировщиков, внимательных сисадминов, осторожных безопасников и продвинутых девопсов трудятся технические писатели. Как правило, они одновременно суровые, дотошные, внимательные, осторожные и продвинутые, потому что именно на них лежит ответственность как за внутреннюю документацию, так и за корректные, грамотные, лаконичные и точные инструкции для пользователей. И писать желательно без девяти прилагательных в одном предложении, как строчкой выше 🙂
Сегодня поговорим об этих ребятах, о профессии, о людях в ней и о том, стоит ли войти в айти именно через вакансию техписа?
NB И да, обязательно читайте цитаты членов сообщества техписов — они рассказывают о самом актуальном в профессии из первых рук.
Компания у нас на full-remote, поэтому заседание кружка параноиков мы проводим как-то так. Иногда под банджо в углу.
В жизни любого проекта наступает катастрофа. Мы не можем заранее знать, что именно это будет - короткое замыкание в серверной, инженер, дропнувший центральную БД или нашествие бобров. Тем не менее, оно обязательно случится, причем по предельно идиотской причине.
Насчет бобров, я, кстати, не шутил. В Канаде они перегрызли кабель и оставили целый район Tumbler Ridge без оптоволоконной связи. Причем, животные, как мне кажется, делают все для того, чтобы внезапно лишить вас доступа к вашим ресурсам:
Макаки жуют провода. Цикады принимают кабели за ветки, и расковыривают их, чтобы отложить внутрь яйца. Акулы жуют трансатлантические кабели Google. А в топе источника проблем для крупной телекоммуникационной компании Level 3 Communications вообще были белки.
Короче, рано или поздно, кто-то обязательно что-то сломает, уронит, или зальет неверный конфиг в самый неподходящий момент. И вот тут появляется то, что отличает компании, которые успешно переживают фатальную аварию от тех, кто бегает кругами и пытается восстановить рассыпавшуюся инфраструктуру - DRP. Вот о том, как правильно написать Disaster Recovery Plan я сегодня вам и расскажу.
Самые первые бизнес-требования были оставлены нашими предками в виде наскальной живописи, некоторые из которых добрались и до наших дней.
О том, как поменять подходы к написанию и пониманию бизнес-требований, чтобы результат от их реализации не был первобытным, расскажем в статье.
Салют! На связи Ганзюк Владимир. Тружусь инженером по нормативно-справочной информации (НСИ) в компании Bimeister.
Хочу поделиться с вами опытом работы с Excel: расскажу, как можно ускорить выполнение рутинных задач при работе с составлением наименований согласно нормативно-технической документации (НТД).
Статья про то, как можно собрать docx-файл из git(adoc)-дерева.
По мнению автора, статья может быть интересна тем, кто хочет уйти от стандартных методов хранения документации. Ведь техническая документация всегда лежит на стыке кода, практик devops_а и нас, простых читателей.
Расскажу, за счет чего поддержка не пробила дно, а стабильно вывозит 25 000 обращений в месяц, экономя при этом 6,5 млн рублей в год. Расскажу, как мы этого добились.
Делюсь своим опытом организации процесса управления изменениями RFC (Request for Comment) и подключения к нему заказчика. Это помогает не разочаровываться в продукте, сравнивая ожидания с реальностью, и исключает ситуации, когда задачи приходят со сроками «вчера». В тексте вы найдёте пошаговую инструкцию по подготовке к проектированию и разработке продукта, а также лайфхаки для решения возможных проблем. Статья будет полезна тем, кто работает на переднем крае команды разработки: руководителям проектов, аналитикам и Product owner.
Sphinx был разработан 21 марта 2008 года, и является генератором документации в Python. Сам он так же был написан Python и преобразует файлы reStructuredText в HTML-вебсайты и другие форматы, включая PDF, EPub, Texinfo и man. Sphinx позволяет автоматически генерировать документацию из исходного кода, поддерживает математические записи и подсветку кода. Он используется для автоматизации создания и загрузки документации с помощью Read the Docs после каждого commit.
Приветствую, друзья! Меня зовут Александр Вихарев, и я работаю системным аналитиком в проектах для Fix Price.
Одной из самых сложных задач при работе с документацией является сверка документов. Причем сверка трудна и с точки зрения программной реализации, если заниматься этим самостоятельно. Для нас же эта задача особенно важна, поскольку все документы должны подписываться только теми людьми, у которых есть на это полномочия. В противном случае это может привести к правовым и финансовым проблемам — например, при подписании договоров на оказание услуг. Также могут наблюдаться и несовпадения в предварительно согласованной и подписанной версиях, что при ручной проверке выявлять долго.
Чтобы избежать этого и освободить время специалистов компании, занимающихся сверкой документации, было решено разработать свою OCR-систему на основе решений внешних поставщиков. Технология OCR (optical character recognition, оптическое распознавание символов) позволяет извлекать текстовые слои из отсканированных документов для сверки и переводить их в удобные для работы форматы.
В декабре 23-го года Material for MkDocs обновился до версии 9.5, но из-за регрессов переходить на него многие не решились. Но сейчас версия уже достаточно стабильная и исправленная, поэтому я хотел бы поделиться с вами, что нового привнесла эта версия и какие лайфхаки я применил при переходе на эту версию при работе с документацией (и вам советую перейти также).
Наверняка вы создавали open source проекты и выкладывали их на GitHub, но я уверен, что очень немногие из вас создавали документацию для этих проектов. В этой статье я расскажу, как создавать и публиковать доки максимально просто.
Документация будет создаваться на основе исходного кода, она будет обновляться при каждом коммите и при этом будет доступна через интернет. Документирование происходит через Doxygen, в качестве хостинга выступает GitHub, а за обновление документации отвечает GitHub Pages.
Как правило, работа с документацией — это последний этап любого проекта, связанного с данными (data science, data visualization и т. д.), проектированием и разработкой ПО. Речь о создании и редактировании библиотек, файлов README, обучающих материалов и др. Среди всех преимуществ VScode — его уникальная экосистема расширений. И особенно впечатляют те, что помогают работать с документацией. В этой статье поделюсь самыми полезными из них.
Онтологический инжиниринг в области Управления бизнес-процессами (BPM). Семантический BPM (Business Process Management), впрочем, как и семантический ЕА (Enterprise Architecture), – это заимствование концепций (подходов к описанию и онтологизации) \ инструментов Linked Data к указанным направлениям (формализация процессов и архитектур предприятий).
«Красная нить»: когда мы формализуем процессы - мы говорим об одном и том же, но на разных языках (нотациях), поэтому стандартизация Языка семантики, онтологических концептов BPM (EA) – важная, но еще недостаточно популяризированная составляющая развития BPM (следующий этап, ВРМ 3.0). Отделение («мух от котлет») семантики от синтаксиса позволит «рафинировать» понятийный (смысловой) анализ бизнес-процессов и при их аналитике оперировать базовыми (семантическими) концептами (образами).
В Semantic BPM, как и в Semantic Web (семантическая паутина), смысл представленного процесса \ архитектуры понятен не только человеку, но и машинам и они могут его читать и обрабатывать. Эти смыслы, обычно передаваемые «человек – человек» на языке синтаксиса / графической грамматики через нотации VAD, EPC, BPMN, UML (плюс еще несколько десятков подобных вариантов \ форматов «обертывания», включая Дракон), исходно формализуются на языке семантики (стек Linked Data или аналогичный) и уже потом упаковываются в схемы с конкретной нотацией («пишутся» на языке какой-либо нотации). Для единого понимания смысловой составляющей схем применяется общая ВРМ-онтология, толковый словарь ВРМ.
