Всё о деятельности технических писателей
Представьте, в требованиях ошибка или документация составлена криво. Требование уходит в разработку, программист неверно его истолкует и реализует фичу с искаженной функциональностью. Если это заметит тестировщик, отправит баг-репорт. И это ещё хороший сценарий! В реальной жизни не все баги исправляют с первого раза, а порой они попадают в прод с печальными последствиями. Как мы тестируем документацию — в продолжении.
Несколько лет назад я услышал от одного коллеги историю. Он в то время работал начальником отдела технической документации в 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.
Богатый язык инженера - это ещё один способ утвердить свой профессиональный уровень в глазах окружающих.
- Ооо, ты инженер конструктор?
- Да!
- Скажи что-нибудь как инженер конструктор!
-Крыльчатка насоса.
- Бог с ним, отправляй, по замечаниям исправим...
Профессия «Инженер» - компактное название с громоздким синтаксисом и семантикой. Благодаря труду инженеров страны развиваются, а население выходит на новый уровень жизни. Каждый из нас хоть раз восторгался видом чего-то нового – например, ракеты или новой машины. Мы путешествуем в разные страны, в том числе, с целью посмотреть на технические выставки и развитие стран, то есть, на работу инженеров. Однако за каждым открытием и творением стоит ни с чем не сравнимый труд. И в каждом открытии и творении стоит инженерная мысль, возможно, уникальный проект инженера.
Чем проще и понятнее описаны требования — тем меньше багов будет в функционале. Потому что не будет разных прочтений, додумок и прочего. А еще в простыне текста легко потеряться и что-то просто забыть реализовать.
Как же сделать ТЗ понятнее? Можно улучшить текст — вместо скупого текста составить вариант использования. А можно использовать визуализацию. То есть добавить в требования картинки, диаграммы, таблицы...
Причем сделать это может не только аналитик, но и любой член команды. Тестировщикам особенно полезно визуализировать ТЗ, потому что это помогает сразу увидеть проблемные места и уточнить их ещё до реализации. Раннее тестирование и всё такое =)
А ещё техники, помогающие лучше понять требования, относятся к техникам тест-дизайна. Значит, о них стоит знать! В одну статью всё запихивать не стала и сделала отдельные:
В заголовке использовано слово сложной, под которым можно понимать все, что угодно. Утверждение о том, что 2 * 2 = 4, если вдуматься, тоже очень не просто. Но в данном случае всё банальнее. Речь идёт о ЕСКД, ГОСТ, ОСТ и тому подобных скучных терминах, отягчаемых бюрократической процедурой согласования.
Года полтора назад мы втянулись в проект по разработке небольшой отраслевой информационной системы. По этой небольшой системе необходимо было разработать с полсотни взаимоувязанных документов и согласовать их не меньше, чем с сотней человек.
Сразу решили, что попробуем сделать документацию актуальной, т.е. обойтись без покраски травы в зелёный цвет. И сразу решили, что это будет Asciidoc. Почему? Потому что из текстовых языков разметки для подготовки документации он наиболее функциональный, а разворачивать неповоротливые DITA и Docbook не хотелось.
Пройдя определённую боль, мы с коллегами решили ей поделиться.
Пост о том, зачем и как аккуратно вести проектную документацию, даже если у вас Agile. Делюсь перечнем и структурой полезных документов и рекомендациями по работе с ними.
Речь пойдет в основном о внутренних документах, которые обычно никто не просит писать, но которые на самом деле нужны команде.