Всё о деятельности технических писателей
Всем привет! Мы продолжаем разбирать наши решения. Сегодня расскажем о том, как, используя генератор Material for MkDocs, можно создать несложный, но удобный статический сайт с документацией (и не только!).
А ещё как встроить его в CI/CD для автосборки и автопубликации (мы используем Gitlab CI, о чём подробно рассказывалось в предыдущем туториале), а также как использовать плагины к генератору чтобы, к примеру, создавался не только сайт, но и его pdf-представление.
Добро пожаловать под кат!
Недавно, на одном из митингов моей команды, была поднята проблема отсутствия документации внутри кода. Было решено назначить ответственного за ведение документации. Нужно было найти подходящие инструменты документирования, определить стиль и регламент, представить решение команде. Я решил, что возьму эту задачу на себя, так как для меня это особенно важный вопрос. Мне, как новому сотруднику, было довольно тяжело разобраться в уже существующем коде без документации, и упустить возможность повлиять на ее появление я просто не мог. В итоге, в процессе определения стандарта для нашей команды и появилась эта статья. Я подумал о том, здесь присутствуют довольно интересные мысли, поэтому решил поделится ими здесь.
Привет, меня зовут Татьяна, я — старший технический писатель в Центре разработки Orion Innovation. Недавно нам пришлось переводить в Agile крупный проект. Несколько Scrum-команд разработчиков, довольно обширный стэк документов, многие из которых устарели просто потому, что в каскадной разработке писатели не успевали их обновлять. Служба поддержки завалена жалобами от пользователей: «Но у вас же так написано, почему не работает?»
Сразу спойлер: интеграция техписов в Agile прошла успешно, хоть и не всегда гладко. Благодаря этому опыту, мы выработали несколько рекомендаций, которыми хочу поделиться.
Представьте, в требованиях ошибка или документация составлена криво. Требование уходит в разработку, программист неверно его истолкует и реализует фичу с искаженной функциональностью. Если это заметит тестировщик, отправит баг-репорт. И это ещё хороший сценарий! В реальной жизни не все баги исправляют с первого раза, а порой они попадают в прод с печальными последствиями. Как мы тестируем документацию — в продолжении.
Несколько лет назад я услышал от одного коллеги историю. Он в то время работал начальником отдела технической документации в IT компании. Дело было на собрании, посвященном знакомству с новым техническим директором. Тот, пожав моему коллеге руку и узнав о его роли, пошутил: “Документация? Так ее же не читает никто! Двадцать первый век на дворе”.
Вряд ли кому-то из нас было бы приятно оказаться на месте этого человека. Но, коллеги, положа руку на сердце, нет ли в подобном отношении нашей вины? К сожалению, я нередко сталкиваюсь с ситуациями, в которых документация, официальная или нет, не может мне помочь. А ведь ее кто-то писал, тратил время и усилия. Зачем это было сделано? И как можно сделать лучше? В этой статье я поделюсь своим видением того, как писать документацию, приносящую реальную пользу читателям.
На одном из утренних дэйликов, мобильные разработчики подняли вопрос о том, что документация по API не соответствует действительности. По горячим следам быстро нашли, что действительно есть нестыковки: разработчик пофиксил баг, но не обновил документацию по роуту. Так как такое уже случалось не впервые - была заведена задача на подумать, что можно с этим поделать.
Ждать долго не пришлось, при обновлении на сервере PHP c 7.2 до 7.4 - мы получили страницу с описанием ошибки, вместо документации. Ошибка найдена в библиотеке, которую мы использовали для рендеринга UI документации. ПР на гитхабе был создан быстро, но провисел в статусе open почти неделю. После этого, тикет насчет документации пошел в работу.
Продолжая тему использования Asciidoc (и других аналогичных форматов) для организации процессов непрерывного документирования, хочу рассмотреть тему автоматический генерации технической документации.
Автоматическая генерация документации — распространенный, но очень расплывчатый термин. Я понимаю под этим термином извлечение для представления в удобном виде информации, содержащейся в исходном коде и настройках документируемой программы (информационной системы).
Привет! Я Катя, руководитель группы технических писателей в Ozon. Сейчас нас уже 9 человек и целая платформа документации, но коллеги всё ещё не всегда понимают, чем мы занимаемся :)
Из непонимания появляются запросы вида: “Хотим себе собственного техписателя в команду, но не знаем, чем именно он будет заниматься”. В итоге команда подстраивается под тренды и заводит себе документацию, но через пару месяцев оказывается, что доку не читают, а техписатель плавно превратился в аналитика.
Поэтому пришло время делиться опытом и рассказывать о каких-то концептуальных штуках :)
В этой статье хочу рассмотреть возможности Asciidoc в части обеспечения требований соответствия документов требованиям единой системы конструкторской документации (ЕСКД), конкретно ГОСТ Р 2.105—9 (далее ГОСТ ЕСКД). Почему именно Asciidoc, я писал здесь.
Сразу уточню. Вопрос форматирования документа здесь не рассматривается. Создающий документацию не должен задумываться о форматировании. Как системный аналитик я создаю содержание и контролирую его структуру. Для получения документа, соответствующего ГОСТ ЕСКД или другому аналогичному стандарту, я должен нажать кнопку и получить корректно отформатированный документ в любых требуемых вариантах: pdf, Open Document (Libre
Office/Open Office), Open XML (Microsoft Word) и прочих.
После работы над https://github.com/CourseOrchestra/asciidoctor-open-document уверен,
что все проблемы форматирования решаются адекватными усилиями.
Рассмотрим структуру документа Asciidoc, соответствующего требованиям
ГОСТ ЕСКД.
Привет! Я Илья Тананаев. Руковожу отделом первой линии техподдержки в ITSumma. И хочу поделиться опытом, как из поиска решенияпроблемы пропущенных чатиков с клиентами мы построили кузницу кадров. Успешно успевая при этом обрабатывать 3k+ клиентских обращений в сутки.
Пару лет назад мы столкнулись с обычной проблемой: админы техподдержки оказались не настолько мультизадачными, чтобы успевать тушить все пожары, решать текущие проблемы и при этом следить за миллионом чатов с клиентами.
Придумали простое и утилитарное решение — поставить между высококвалифицированными админами и клиентами первую линию поддержки, которая взяла бы на себя относительно простую работу по уточнению запросов. Но дальше случилось так, что бонусом к изначальной задаче мы открыли отличный способ развития компании и путь обучения недавно пришедших в IT специалистов.
И в этой статье расскажу, как мы помогаем расти нашим сотрудникам и что из этого вы можете применить у себя в любой компании, чтобы справиться с дефицитом кадров.
Наличие технического писателя в команде воспринимается либо как нечто само собой разумеющееся, либо как нечто вызывающее вопросы “Ты кто? Ты что тут делаешь?”.
Но когда технический писатель уходит из команды, его отсутствие можно сравнить с отсутствием маленького кусочка в большом и сложном паззле. Без этого кусочка можно обойтись. Но внимательный наблюдатель заметит, что картина команда не полная, в ней явно кого-то не хватает.
А именно не хватает человека, который охотно и каждый день берет на себя всю эту писанину. А без нее никак на проекте.
Почему же такой человек в один прекрасный день может взять и уйти?
В этой статье хочу поделиться своим опытом, без отсылки на умные исследования Гарварда и Стэнфорда. Для себя выделила пять причин. Ими делюсь.
В рунете я почти не встречал материалов о том, как писать расширения для MediaWIki. Основной стартовой точкой был и остается официальный сайт платформы, но там процесс расписан не очень дружелюбно по отношению к новичкам. Попробуем же это исправить!
В этой статье я покажу, как написать простейшее расширение для Медиавики, включающее в себя новый метод API, расширение парсера и немного js/css для фронтенда. А чтобы не было скучно, приплетем сюда работу с Google Knowledge Graph.
Ключевым фактором для по-настоящему массового продукта является простота использования, функциональность и стоимость. Как принципиальный сторонник бесплатного ПО я являюсь давним пользователем технологии АsciiDoc и считаю, что на сегодняшний день она располагает самым большим потенциалом.
Функциональность Markdown и даже reStructuredText ограничена, а порог входа для DocBook и DITA достаточно высок, чтобы поставить на них крест как на массовом продукте. Нужна золотая середина между функциональностью и простотой. Система документации должна быть одинаково удобна на всех этапах жизненного цикла программного продукта: проектирование, реализация, сопровождение. В идеале она должна прекрасно применяться и вне задач создания программных продуктов.
Основной проблемой, с которой я сталкивался при подготовке документации в АsciiDoc – это отсутствие полноценного конвертера в docx (MS Word) или odt (OpenOffice/LibreOffice) для сдачи документации заказчику в этих его любимых форматах. Также эти форматы очень удобны для сравнения выходных документов.
В последние несколько лет в среде технических писателей все больше на слуху концепция Docs as Code. Если вы раньше не сталкивались с этим термином, он обозначает подход к разработке технической документации с использованием тех же инструментов и процессов, что и написание кода. Если DocOps это про процессы и коллаборацию, то Docs as Code — про инструментарий, при помощи которого мы несмотря ни на что. Мы выбрали этот подход, когда создавали портал документации Plesk.
В этой статье я кратко расскажу, что такое Docs as Code и зачем оно нужно, а затем дам несколько советов относительно того, как это чудо враждебной техники внедрять, сдобрив всю историю рассказами о тех граблях, на которые мы наступили, топая в светлое будущее. Я старался писать такую статью, которая пригодилась бы мне в 2017 году, когда мы эту кашу заваривали.
Это небольшая заметка посвящена теме оформления результатов создания ИТ-продуктов для органов государственной власти и крупных корпораций. В настоящее время при сдаче работ указанным организациям требуется представить десятки документов (часто в бумажной форме), подтверждающих соответствие выполненных работ требованиям технического задания.
Вопрос заключается в том, обеспечивает ли такое количество документации надлежащее качество выполненных работ?
Для тех, кто в теме, давно уже не секрет, что громадное количество «макулатуры», сдаваемой заказчику, часто служит прикрытием творческой несостоятельности заказчика или разработчика, которые не могут правильно поставить задачу и сделать качественный продукт и прикрывают это объёмом технической документации. «Макулатура» также служит обоснованием завышенной стоимости программного продукта.
Чиновника это устраивает, так как при любой проверке можно показать объём странице-километров документации и избежать ответственности за неработающее программное обеспечение.
Корпоративная база знаний — это не только и не столько площадка на базе какого-нибудь вики-движка, сколько люди и процессы, стоящие за ней. При внедрении вики-платформы самое сложное — это не тонкая настройка движка или попутных расширений: самое сложное — это сделать так, чтобы коллеги наконец начали пользоваться поднятой вами базой знаний.
Я начал заниматься базой знаний, будучи зеленым джуном, так что все описанные в посте рекомендации применимы даже в том случае, если у вас нет административных или финансовых ресурсов. Иными словами, советов в духе "просто заставьте всех писать и штрафуйте непослушных" тут не будет, мы пойдем другим путем.
В прошлой статье я предложил рассмотреть Xwiki, как бесплатную замену Confluence и заодно пообещал поделиться несколькими советами по настройке.
Вот уже больше полугода я использую Xwiki в качестве базы знаний для небольшой команды разработчиков.
В процессе работы у меня возникали определенные трудности, документация не помогала, а ответов на англоязычном форуме приходилось ждать с большим вожделением, чем первого глотка пива в выходной.
Мне бы хотелось облегчить жизнь энтузиастам из волшебного мира документирования, поэтому я решил поделится своими наработками.
На текущий момент я планирую подготовить мини цикл из четырех - пяти статей.
В первой статье мы поговорим о простых приемах настройки панелей в Xwiki.