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

Привет, Хабр! Сегодняшняя статья целиком посвящена рабочим местам и уголкам для хобби сотрудников Selectel. Всегда было интересно читать похожие посты других компаний, включая сам Habr. И мы решили поделиться своей историей. Если у вас будут вопросы, задавайте в комментариях, ответим. Кстати, если есть желание, хвастайтесь в комментариях своими рабочими местами, хобби или DIY-проектами.

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

Источник

Водка и шампанское, огонь и лёд, физика и лирика, экспертиза и нарратив — любой технический автор попадает на территорию, где сталкиваются два противоположных направления: техническое и литературное. Как сильно они конфликтуют? Где начинаются и где заканчиваются их границы? Как найти нужный баланс между этими направлениями и написать крутой технический текст, который может выиграть конкурс? Обо всём этом мы решили поговорить с тремя опытными хабраавторами и вместе с нашими партнёрами из SBTG.ru организовали для них творческий вечер, где они расскажут о том, как надо создавать статьи для Хабра. Подробности — под катом.

Что пользователь хочет видеть в пользовательской документации? Что его в ней раздражает? Эти вопросы задаёт себе каждый, кто пишет такую документацию, но далеко не каждый правильно отвечает на них. Совсем небольшой процент пользователей читает документацию. Давайте разберёмся, почему так и как сделать пользовательскую документацию эффективной и изменить отношение пользователей к ней.

Я работаю в коммерческой разработке с 2011 года. С конца 2012 занимаюсь разработкой под iOS. Свою первую техническую статью я написал на Хабре в начале 2017 года про подход к локализации мобильных приложений. Потом выпустил ещё несколько статей по iOS-разработке на Хабре и в конце 2017 года я перешёл в новую компанию и решил вести блог про solution architecture https://medium.com/@nvashanin, где начал описывать общие концепты, обязанности архитектора, его скилл-сет и т.д. К лету 2020 года количество просмотров моих статей перевалило за 800 тысяч, а количество времени, которое люди потратили на прочтение — больше 6 млн минут, или около 12 лет чистого времени. Флагманская статья была переведена другими людьми на разные языки: например, польский или испанский.

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

Привет! Меня зовут Даша Григорьева, я технический писатель в компании 65apps. Мы занимаемся разработкой сложных мобильных решений, и моя задача — подготовка технической документации по проектам. Очень часто роль технического писателя бывает недооцененной в компании (не у нас, конечно). Поэтому я хочу рассказать, зачем компании-разработчику нужен такой специалист, что такое технический проект, чем он отличается от ТЗ и почему это все необходимо для разработки мобильного приложения.

Я – технический писатель, 4 года снимаю обучающие видеоролики для системы Directum RX. В беседе со мной коллеги часто слышат:

• «К ролику пришли замечания»;
• «Дай, пожалуйста, доступ к роликам»;
• «Любовь к роликам» и тому подобное.

Наверное, в их головах рисуются примерно такие картинки:

Многие уже давно или активно используют или смотрят в сторону модели хранения и публикации документации как кода, это значит применять к документации все те же правила, инструменты и процедуры, что и к программному коду, например, хранить в репозитории, прогонять тесты, собирать и релизить в CI/CD. Этот подход позволяет поддерживать документацию актуальной к коду, версионировать и отслеживать изменения, используя привычные инструменты разработки.

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

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

На web-проектах Альфа-Банка используется фреймворк для автоматизации тестирования Akita, который использует для BDD-сценарии. К настоящему моменту фреймворк набрал большую популярность благодаря низкому порогу входа, удобству использования и возможности тестировать верстку. Но мы решили пойти дальше — на основе описанных тестовых сценариев формировать документацию, тем самым сильно сокращая время которое аналитики тратят на на извечную проблему актуализации документации.

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

• скриншоты;
• значения переменных (config File, учетные записи пользователей и т.д.);
• статусы и параметры запросов.

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

Начну не с моего типичного “Привет, Хабр! У нас тут очередной крутой релиз”, а с “Привет, меня зовут Настя, я ПММ в JetBrains и я отвечаю за наши инструменты для C++”. Или нет, попробую еще раз, вот так: “Привет, пишет вам C++ разработчик с 8-летним стажем, который 5 лет назад нашел-таки себе применение в любимой и знакомой компании мечты – JetBrains, а потом в сутках внезапно закончились часы, а идеи всё прут”.

Нет, это не традиционный пост о поисках кандидатов на вакансию. Я попытаюсь рассказать про то, почему инструментов для C++ у нас несколько и какие есть идеи и планы у нас на их счет, а еще почему вы не забудете C++, если перестанете писать на нем как разработчик, а станете PMM-ом (спойлер, если вы не член комитета стандартизации языка C++, то у вас большие шансы узнать язык даже лучше). А если после этого вам захочется поучаствовать в этом в роли PMM-а, то я буду рада вашим резюме на anastasia.kazakova@jetbrains.com.

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

Рассказывает Юрий Никулин, руководитель службы разработки технической документации.

Для начала давайте определим, что такое производительность. В классическом понимании, это время на производство единицы продукции или количество продукции, произведенное в единицу времени.

Например, это количество произведенных телефонов за месяц или количество времени на производство тысячи телефонов. Возникает вопрос, как измерять интеллектуальный труд, которым занимается наш отдел.

Сегодня поговорим о том, как избавиться от документации, которая не работает, описывает какое-то легаси, не организована, не соответствует идентичности вашего бренда, да что там — просто плохой документации. Чтобы затем подготовить и реорганизовать хорошую, валидную, логично организованную и соответствующую идентичности бренда документацию. И как только вы сможете избавиться от документации — все станет радужно и прекрасно.



Под катом перевод доклада Александры Уайт, технического писателя из компании Google, на конференции Write the Docs Prague 2018. А уже через неделю 26 апреля 2019 Александра выступит на нашей конференции KnowledgeConf с докладом «How to create compelling multimedia documentation». Александра расскажет, как встроить мультимедиа форматы (видео, аудио, gif) в процесс создания артефактов и упаковки знаний, когда мультимедиа форматы подойдут лучше всего, а когда не будут работать, как измерять эффективность мультимедиа артефактов и преодолевать их ограничения.

Мы в каждый год устраиваем отдельную конференцию для всех, кто причастен к созданию технических текстов. В этом году она пройдет 4 апреля.

На этот раз наша конференция — особенная. И тому есть две причины. Во-первых, мы впервые пригласили внешних спикеров. От «Лаборатории Касперского» будет только два доклада, а остальные — от сотрудников компаний Intel, Positive Technologies, Logrus IT и ECommPay IT.

Привет, Хабр! Представляю вашему вниманию перевод статьи «What do UX writers do all day?» автора Yael Ben-David.

Осознавая тот факт, что существование такой должности, как UX-писатель, довольно спорно, непонятно, и подходит далеко не любому проекту, я все же решил рискнуть, и предложить сообществу статью, которая приоткрывает контекст работы UX-писателей. Заранее всем спасибо, кто уделит время прочтению.

Советы по грамотному написанию технической документации для пользователей.
Часть 2

Продолжение руководства нашего технического писателя Андрея Старовойтова, которое поможет сделать вашу пользовательскую документацию проще и понятнее.

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

В этой части мы подробно разберем топики, из которых в основном состоит пользовательская документация (особенно User’s Guide) – а именно task-топики, в которых рассказывается, как решить конкретную задачу.

Советы по грамотному написанию технической документации для пользователей.
Часть 1

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

На этот раз под катом – руководство нашего технического писателя Андрея Старовойтова, которое поможет сделать вашу документацию для пользователей проще и понятнее (описанные приемы применяют при документировании своих продуктов Apple, Microsoft и другие компании).

Хотя второй по счету митап Write the Docs Moscow состоялся уже месяц назад, опубликовать отчет и краткие конспекты докладов никогда не поздно. Мы успели обсудить ну практически все: от документирования RESTful API до профессиональных траекторий техписателя.

Митап, кстати собрал не только «техписательское гетто», но и широкий круг других специалистов, кто так или иначе работает испытывает боль с документацией на проекте: тимлиды, аналитики, тестировщики и даже один технический директор.

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

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

Меня зовут Андрей Поляков, я руководитель группы документирования API и SDK в Яндексе. Сегодня я хотел бы поделиться с вами докладом, который я и моя коллега, старший разработчик документации Юлия Пивоварова, прочитали несколько недель назад на шестом Гипербатоне.


Светлана Каюшина, руководитель отдела документирования и локализации:
— Объемы программного кода в мире в последние годы сильно выросли, продолжают расти, и это влияет на работу технических писателей, которым приходит все больше задач на разработку программной документации и документирования кода. Мы не могли обойти стороной эту тему, посвятили ей целую секцию. Это три взаимосвязанных доклада, посвященных унификации разработки программной документации. Я приглашаю наших специалистов по документированию программных интерфейсов и библиотек Андрея Полякова и Юлию Пивоварову. Передаю им слово.

Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.