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

Hola, Хабр! Я — технический писатель и за свою длинную карьеру в ИТ, нигде и никогда не сталкивался с ситуацией переизбытка в командах технических писателей. Наоборот, почти повсеместно в компаниях есть множество продуктов и проектов, в которых документация неполная, неточная, устаревшая и покрытая паутиной, а самих «техписов» хронически не хватает. Опытные спецы, умеющие читать код, документировать алгоритмы, описывать БД и API — это вообще люди уровня «ошибка выжившего». И, возможно, я нашел ответ на этот вопрос.

Действующий 184-ФЗ «О техническом регулировании», принятый Россией при вступлении в ВТО требует, чтобы любая продукция была безопасна и не вводила людей в заблуждение.

Для реализации этих требований вводятся технические регламенты, которых в настоящее время 54 (прогнозируется необходимость около 2000). Бывшие в СССР ГОСТы, СНиПы и СанПиНы есть и сейчас, но в 184-ФЗ сказано, что они принимаются на добровольной основе. При этом в статье 46 184-ФЗ написано, что если какая-то вещь касается безопасности и правдивости, то необходимо применять существующие ГОСТы, СНиПы и СанПиНы (по нормам ст. 309 ГК РФ).

То есть, если Вами использовано слово «рубильник» вместо «переключатель», то Вас могут признать нарушителем 184-ФЗ и применить ст. 14.4 КоАП РФ.

Представленный нами словарь станет Вашим помощником в выборе правильного термина и оградит Вас от некоторых проблем.

Мой первый on-call выдался нелегким. Недели тренингов и обучения не подготовили меня к тому что придется бегать по Slack каналам различных команд и искать того, кто может что либо знать о какой-то из частей системы. Оказалось что многие страницы в корпоративной Wiki уже не обновлялись несколько лет. Команды хранили свою документацию кто где хотел: кто в Wiki, кто в Google Docs, кто в GitHub и т.д. Наш on-call был не идеален: 2 человека выходили на дежурство 24/7. Один был ответственен за всю инфраструктуру (MySql, Cassandra, Kafka, ElasticSearch, Nomad и т.д.), второй же был Developer on-call и отвечал за все микросервисы и различные легаси системы, что в сумме давало около 300 различных сервисов от 7 команд на самых различных стеках и фреймворках (Java, Scala, Node, Go). Но что меня больше всего раздражало - так это невозможность быстро оценить на высшем уровне как проходит и обрабатывается запрос от пользователя. Диаграммы для разных бизнес частей точно также были либо устаревшими, либо без прилегающей документации, либо для какой-то бизнес логики не было ничего. И вот тогда мне пришла идея, что было бы неплохо иметь диаграммы, в которых можно не только нажать на любой элемент и добыть о нем более детальную информацию, но также получить ссылки на другие диаграммы и динамически их подгружать. Мне хотелось иметь возможность быстро разобраться в неизвестной распределенной системе, не переключаясь между диаграммой и документацией в Google Docs или Wiki. Именно так я начал работать над проектом Schem.io.

Предупреждение: в статье содержится большое количество GIF-изображений.

При составлении контрактов, технических заданий, проектов термины становятся юридически значимыми определяющими условиями. В текущих условиях, когда требования ст. 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 млн рублей в год. Расскажу, как мы этого добились.

Хабр, привет! В прошлых статьях про UML (Часть 1, Часть 2) мы узнали что такое язык моделирования UML и зачем он нужен, а также рассмотрели диаграмму классов и диаграмму компонентов. Сегодня я хочу продолжить тему проектирования процессов и остановиться на диаграмме объектов.

Делюсь своим опытом организации процесса управления изменениями 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, но из-за регрессов переходить на него многие не решились. Но сейчас версия уже достаточно стабильная и исправленная, поэтому я хотел бы поделиться с вами, что нового привнесла эта версия и какие лайфхаки я применил при переходе на эту версию при работе с документацией (и вам советую перейти также).