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

Начальник за апгрейд, тем более сам видит, что часто разрабы забывают передать далее, что добавили новые фишки в код и документирую я уже в режиме "нужно было вчера". Моя задача  сейчас - подобрать инструмент. Изначально его мессендж был "Давай уйдем от Indesign в Word", ну ок. А вот такой глобальный апгрейд придется и ему обосновать

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

Выбирая docs as code, вы построите мост между вами и разработчиками. Они смогут ревьюить документацию, исправлять мелкие недочёты самостоятельно, а со временем и писать черновые версии самостоятельно. Выбирая любой другой инструмент, вы построите не мост, а стену, через которую вам будут перекидывать задачи.

Мне нужно учитывать мнение разработчиков при выборе инструмента для документирования 😂 или это только для техрайтера? В парочке проектов используется Doxygen для небольшого блока комментариев. На этом сё, больше доков нет

Настройка - это часть установки. Поэтому не стоит помещать в отдельный хелп - файл.

Вообще да. Но такое пожелание у клиентов - по нажатию F1 из программы открывает хелп, поэтому перенесли этот блок в отдельный файл

Никогда ранее не задумывалась, в чём удобство, но ведь установщики всё равно открывают отдельный PDF со схемами установки  🤔

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

Раз уж пошла речь про инструменты, задам свой вопрос)
Был у кого-нибудь опыт работы с Github Pages или Gitlab Pages?

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

Всё так и есть, или я что-то упустил?)

docs-as-code это не про документирование кода, а про использование практик, применяемых при кодировании, в написании (хотя, здесь будет лучше слово более общее слово authoring) документации. Т.е. docs-as-code не имеет ничего общего с документированием *кода*. Так что если у разработчиков его нет, то это совсем НЕ означает, что подход не работает.

Да, вещи ортогональные.

GH Pages это только способ захостить статический сайт.

аналогично gitlab pages. Всё равно придётся выбирать ssg. у гитлаба ещё есть фича Wiki, может оказаться что вам её достаточно

ИЩЕМ ТЕХНИЧЕСКОГО ПИСАТЕЛЯ (Technical writer)

#вакансия #техническийписатель #technicalwriter #ITjob #fulltime #vacancy #technical writer #wanted_TW

Компания - мировой лидер в области разработки устройств и ПО, web&mobile для проверки подлинности документов, денежных знаков, ценных бумаг, решений для прохождения идентификации по фото и селфи-видео (liveness) приглашает в свою команду Технического писателя (Technical Writer).

  Задачи:
- описание продукта и подготовка документации по продукту
- подготовка инструкций, примеров использования продукта
- поддержание документации в актуальном состоянии
- подготовка release notes
- сбор информации о новых возможностях продукта и оформление в виде статей для блога
- публикация и продвижение документации
   
 Must:
- письменный английский от С1
- опыт написания тех. документов на англ языке
- опыт работы техническим писателем от 3-х лет
- аналитическое и системное мышление, внимание к деталям
- понимание терминологии разработки ПО
- technically savvy
   
  Мы предлагаем:
- работа в сильной команде профессионалов
- работа с клиентами со всего мира
- собственные новые продукты (не outsourcing, не legacy support)
- участие в создании продукта, который используют миллионы людей
- ЗП привязана к курсу (обсуждаем индивидуально в зависимости от опыта, ориентир - до 2500$)
- ежедневное развитие и повышение профессионального уровня на стыке различных современных технологий (mobile/cloud/hardware)

Bилка до 2500$.
Буду рада подробнее рассказать!

telegram @alina_engineerica
linkedin https://www.linkedin.com/in/alina-engineerica/
viber +375291952020

Уважаемые коллеги, повторно публикую вакансию. На этот раз с вилкой.
#wanted_tw  
Компания: CMA Small Systems https://www.cma.se/  
Локация: не имеет значения, но если интересен офис, то он на м.Динамо  
Формат работы: возможна полная удаленка  
Компенсация: 120-180 gross в зависимости от уровня и навыков  
 
Всем привет!  
Ищем технического писателя. Писать нужно на английском. Сейчас вся дока в ворде, но уже запущен масштабный проект по переходу на rst+Sphinx.  
 
Что нужно делать:  
Разрабатывать документацию к продуктам. В основном это кастомизации имеющихся систем под разных заказчиков.  
Активно участвовать во внедрении и продвижении docs-as-code.  
Возможно потребуется принять участие в описании внутренних процессов.  
 
Что нужно уметь:  
Хорошо и без ошибок писать на английском, соблюдая требования стайлгайдов.  
Писать на любом языке разметки (или иметь желание этому научиться).  
Настойчиво извлекать информацию из людей и источников.  
 
Что еще можем предложить:  
Компенсация питания в офисе. ДМС после испытательного срока. Техника для работы.  
 
Резюме, примеры работ и любые вопросы можно адресовать мне здесь или на почту Denis.Mashutin@cma.ru.

@factorized Семён, а вы будете в этом году проводить Advanced Technical Writing? На сайте до сих пор висит «Осень 2021»

присоединяюсь к вопросу
менеджерам documentat.io тоже писала на почту, ответа нет

Ждем информации

Добрый день! Да, мы определились: очный курс пройдет 18-19 ноября, к началу следующей недели всем записавшимся должно прийти письмо