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

Влияет ли наше состояние на то как мы думаем и что говорим? Как через состояние и мышление повысить качество документации?

Приветствую всех! Меня зовут Катя Фролова, я работаю техническим писателем в RuStore.

В прошлом году документация RuStore переехала на новый движок.

Расскажу, почему мы отказались от хорошего решения ради более хорошего и чего нам это стоило.

Всем привет. Меня зовут Татьяна Цикунова, я работаю системным аналитиком в компании МойСклад, в команде eCommerce. Моя команда специализируется на разработке интеграций сайтов с сервисом МойСклад. Мы помогаем бизнесу автоматизировать процессы: учета, продаж, коммуникаций с клиентами, выход на новые торговые площадки. Также мы разрабатываем интеграции с самыми популярными маркетплейсами на рынке России и зарубежных стран У МоегоСклада уже есть решения для селлеров на Ozon, Wildberries, Яндекс Маркете и Мегамаркете, а также для зарубежных маркетплейсов.

В статье я расскажу о том, что такое эти самые интеграции с маркетплейсами на примере сравнения наших решений для Ozon и Wildberries. 

Сначала приведу немного статистики от Data Insight. Чтобы понимать, насколько сейчас популярна торговля на маркетплейсах, достаточно взглянуть на слайды ниже. 

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

Привет, Хабр! Меня зовут Виктория Юльская, и я старший системный аналитик в Ozon.

Я думаю, здесь найдётся много людей, которые хоть раз работали с документацией API в Confluence. Да-да, те самые километровые страницы на каждый метод — с описанием всего и вся в виде текста, таблиц, диаграмм последовательности и т. д.

Зачастую такая документация API в Confluence устаревает ровно в тот момент, как её закончили писать. После передачи задачи в разработку, как только что-то непонятно, куда все идут? Правильно, к аналитику — «А как это работает? А что это значит? А что если...?».

Ну вот же дока, там все написано... но обычно никто не хочет читать огромную доку на метод, быстрее же спросить. И зачастую у самих аналитиков есть вопросики по актуальности этой документации (уже есть новые договорённости со встреч, комментарии в документации и т. д.).

Есть ли более эффективный способ ведения и поддержания документации API в актуальном состоянии? Давайте разбираться.

Что такое Docs as Code классно описано в статье Docs as Code: введение в предмет.
В двух словах: это ведение документации на языке разметки (Markdown, AsciiDoc) с хранением в репозитории.
Плюшки — все вытекающие от работы с репозиторием.
Минусы — в этой статье.

На осенних Analyst Days прошлого года добрая четверть докладов была посвящена теме Docs as Code. На тот момент конклав аналитиков на моём прежнем месте работы уже 9 месяцев решал, нужен ли на проекте модный-стильный-молодёжный Docs as Code или всё же остаться в дышащем на ладан Confluence. К чему пришли — не знаю. На новом месте работы мы внедрили Docs as Code за неделю — было чёткое понимание проблематики, подход казался выигрышным решением. Используем полгода.

Без толковой API-документации сложно делать открытый продукт и ждать, что его будут развивать пользователи. Часто владельцы сервисов занимаются документацией по остаточному принципу. В итоге разработчику достаётся запутанная инструкция, а интеграция усложняется или просто становится невозможной.

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

У химиков есть известная байка, которую они любят рассказывать молодому поколению. Главный герой этой истории — студент, который пошагово воспроизводил методику одного химического эксперимента из учебника. Он старательно выполнил очередной шаг «добавьте азотную кислоту» и... в лаборатории прогремел взрыв! Когда впоследствии стали разбираться, в чём же дело, выяснилось, что на следующей странице учебника было написано: «... медленно, по каплям».

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

Как же лучше писать и оформлять примечания в технических текстах?

В статье расскажу про Foliant и про возможности по документированию HTTP API с его использованием. Упор сделаю на API, которые описываются с помощью OpenAPI/Swagger. Также вскользь коснусь возможностей по документированию API, описанных с помощью других спецификаций.

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

«Ваша документация — отстой!», «Я её никогда не читаю, всё равно там ерунда написана!», «Эти документаторы опять всё напутали», «Да любая нейросеть быстро напишет это в сто раз лучше», «Там никогда не найти ничего нужного», «А разве у нас есть документация?»

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

C вами Семён Факторович и компания documentat.io. С 2018 года мы помогаем IT-компаниям создавать техническую документацию: пишем документацию на заказ, консультируем инженерные команды по процессам документирования, учим техписателей и инженеров писать документацию.

В январе 2024 года мы провели большой социологический опрос среди техписателей и других IT-специалистов, разрабатывающих документацию. В этой серии статей я делюсь результатами нашего опроса.

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

В этой статье я расскажу об индустриях, в которых работают русскоязычные техписатели, о видах документов, которые они разрабатывают, о востребованности знаний ГОСТ и о том, как всё это влияет на техписательские зарплаты.

Всем привет, меня зовут Влад и я запилил собственный IT стартап в одиночку потратив $100. Я давно хотел проверить свои силы и показать самому себе на что я способен, смогу ли я дойти от: создания идеи, проработки ui/ux, разработки frontend & backend, до публикации продукта и его маркетинга.

Для общего понимания я постараюсь кратко описать свой background. В 14 лет я увлёкся веб разработкой поскольку у меня была команда по игре counter strike и для того чтобы заявляться на турниры, нам требовался сайт, по мере его поддержания, я освоил исскуство владения фотошопом. Этот сайт я начал монетезировать и смотрел как его можно продвигать.

Дальше был универ, где я много писал код на c++, python, c#, писал свои нейронки, программировал роботов, проходил алгоритмы и структуры данных. В это самое время вместе с друзьями начали развивать ивент стартап, который помогал пользователям узнавать расписание, изменения, следить за интересными спикерами. Я занимался ui/ux проектированием и frontend разработкой. В это самое время я изучил первые в своей жизни методологии дизайна: google material design guidelines and Apple Human Interface Guidelines.

Писал диплом на тему: примерка мебели в дополненой реальности на свифте.

Потом был момент, когда мы с партнёрами открыли it outsource компанию на 40 человек разработки, где я был CTO и следил за технологиями в компании на стеке: JS, Typescript, React, Vue, Php, python, nodejs, reactnative.

И весь свой накопленный опыт я хотел применить для создания продукта.

Привет, Хабр! Меня зовут Кирилл Рупасов. Я руковожу группой инженеров SOC (Security Operations Center) в «К2 Кибербезопасность». Я не понаслышке знаю, как порой непросто создавать контент для Центра мониторинга кибербезопасности. Написать одно правило обычно несложно, а вот разработать их связанный комплекс — задача достаточно трудная, особенно для молодых команд.

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

Хабр, привет!

Меня расстраивает несправедливость в мире IT: для новичков-разработчиков есть куча пошаговых инструкций, о там, как разработать API или мобильное приложение. Хочу немного уровнять баланс вселенной, поэтому я написал небольшой гайд для аналитиков для составления документации.

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

В статье собраны рекомендации по подготовке текста к машинному переводу на основе советов IBM (Machine translation tips, вебархив). Они помогут оптимизировать процесс перевода и сократить время на постредактирование. 

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

C вами Семён Факторович и компания documentat.io. С 2018 года мы помогаем IT-компаниям создавать техническую документацию: пишем документацию на заказ, консультируем инженерные команды по процессам документирования, учим техписателей и инженеров писать документацию.

В январе 2024 года мы провели большой опрос среди техписателей и других IT-специалистов, разрабатывающих документацию. Теперь я начинаю серию статей, в которой поделюсь с вами результатами опроса.

В первой статье я расскажу о географии и демографии русскоязычных техписателей — где мы живём, сколько нам лет, каков наш гендерный состав — а также рассмотрю зарплатную статистику в техписательском сообществе РФ.

Привет, хабр! Я технический писатель в компании Bimeister. 

Наша компания занимается разработкой программного обеспечения для автоматизации крупных производств. Вместе с тем мы разрабатываем большой объем технической и проектной документации. Так получилось, что Заказчики наших продуктов стремятся к соблюдению требований государственных стандартов (далее — ГОСТ), поэтому всю отчетную документацию мы пишем в соответствии со стандартами.

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

Требования Заказчика будут проходить красной нитью по всей статье, поэтому сразу приведу цитату, которая успокаивает мне нервы в такие моменты:

Всем привет!

Решил немного отойти от своей любимой темы нейронных сетей и написать небольшой скрипт на Python для работы с конструкторской документацией в САПР «SolidWorks». Так как изначально у меня инженерное образование, то мне периодически приходится заниматься конструкторской деятельностью и, по своему опыту, я знаю, как много иногда приходится тратить времени для оформления чертежей и сохранения их в формате pdf или dwg (особенно, если мы говорим о большом количестве деталей сборок). И тут я подумал, почему не упростить жизнь себе и своим коллегам-конструкторам и не подружить Python и SolidWorks.

В этой статье я вкратце опишу, как можно быстро (буквально за один день) написать простой скрипт, с максимально простым графическим интерфейсом для работы с Системой автоматизированного проектирования SolidWorks. Очень надеюсь, что эта статья поможет всем инженерам-конструкторам в их непростой, но крайне интересной деятельности.

Работа будет состоять из двух основных частей (соответственно и статей будет две):

Часть 1 – Создание общей базы для работы с SolidWorks, написание простого графического интерфейса на tkinter, реализация возможности сохранения чертежей в форматах pdf и dwg.

Часть 2 – Реализация возможности автоматизированного заполнения полей таблицы чертежей из единого excel файла, и самая интересная фича этого проекта: автоматическое создание чертежей деталей из 3D-моделей (для начала реализация простых деталей из листового металла).

По итогу «завернём» программу в один .exe файл для возможности использовать на любых машинах.

В этой статье я расскажу о генераторе документации Sphinx, с помощью которого можно автоматически создавать документацию для модулей Python. Кроме того, я буду использовать шаблон проекта Cookiecutter Data Science в Visual Studio Code (VS Code), поскольку он легко интегрируется в Sphinx и имеет стандартизированную структуру директорий. Официальное пособие по использованию Sphinx — отличный ресурс для пользователей, которые хотят углубиться в детали. А моя статья — это краткое руководство по началу работы с этим инструментом.