Коллеги, поделитесь опытом, у кого как выстроен процесс разработки и последующего ревью документации в связке с фичами, требованиями бэклога?  Как помечаете для ревьюеров в документе (в любом), что "здесь задокументировано это требование"?)

1. Разработчики, пишущие документацию (мои исследования показывают, что это примерно 14-16% от всех разработчиков, и в цифрах - это больше, чем людей, у которых job title "технический писатель"). Ну и, конечно, к этой аудитории мне проще достучаться по имеющимся каналам, и у них есть brand awareness

2. Технические писатели, которые собрали doc-as-code pipeline и пользуются редактором типа VSCode, Atom, Sublime и т.д. + SSG. И, кстати, среди этого сегмента, как ни странно (для меня это было открытием) довольно много людей пишут доки в IntellIJ IDEA (даже среди представителей этого чата)

3. Single writer on a team - когда тебе надо быстро сделать документацию с нуля в новом продукте, желательно вчера, и ты должен быть и писателем и докопсом и дизайнером.

неплохо, спасибо

Я за открытость, поэтому расскажу, какая мотивация за опросом выше. Хочется сделать импорт в md из гугл доков, это связано с некоторыми техническими трудностями. Есть внутренняя уверенность, что фича очень нужная (и не только для техписателей, а для тех, кто пишет, например, блог посты в markdown). Но хочется иметь хоть какой-то пруф в цифрах, чтобы убедить некоторых участников процесса, что игра стоит свеч. Ну и я-то сама продакт "от сохи", то есть техпис с почти пятнадцатилетним стажем, поэтому конечно, в первую очередь хочется сделать максимально полезно для себе подобных :)

2 и 3 пересекаются между собой. Т.е. человек из п.3 переходит (или не переходит) в п.2
В любом случае, ИМХО, п.1 полностью, а п.2 частично - не является подавляющей аудиторией этого чата.
А вы пробовали запостить аналогичное в docops чат от @Nick_Volynkin ? Полагаю, что там было бы больше релевантных ответов особенно по п.2 и полностью релевантные по п.1

Я чего-то не знаю, или почему IDEA отдельно и это открытие? Я ей пользуюсь.

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

Ревью - это не только импорт, но и экспорт. Вопрос - будет ли экспорт В ГД?

хочется поддержать более удобный воркфлоу для ревью, чем перекидывание в Gdoc и обратно

И все-таки РФ аудитория - нерелевантна в этом смысле. Т.к. у вас продукт идет на основные центры разработки: Берлин, Лондон, SF Bay Area, NY, Portland и т.п. Иными словами - можно сделать опрос, но он будет валидным только для РФ аудитории, а здесь своя специфика.

а кто сказал, что я этот вопрос задаю только в этом чате? 😇

>  Хочется сделать импорт в md из гугл доков

А почему разработчики код не комментируют в гуглдоках? Почему вы для них не делаете аналогичный импорт?

Суть подхода «документация как код» в том, чтобы делать всю работу в одном наборе инструментов, привязанном к системе контроля версий. Если техписателям  неудобно комментировать в пулл-реквесте и они убегают в гуглдок — это проблема рабочего процесса. Нужно научить техписателей пользоваться пулл-реквестами или устранить какие-то преграды к этому, а не делать подпорку к проблеме.

Комментируя в гугл-доке мы нарушаем принцип «единая точка правды». Обсуждение задачи становится оторванным от самой задачи и коммита, который эту задачу решает. Будет сложно или невозможно через год или два восстановить обсуждение, которое привело к конкретному решению техписательской задачи.

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

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

Фух, выговорился )

Коля, то, что ты пишешь никак не противоречит моим убеждениям :) И мы в JB тоже не используем GDoc для ревью. Но бывают ситуации, когда ты пишешь отдельный документ, не являющийся частью технической документации. Например, технический или маркетинговый пост в блог. И у тебя нет выбора, кроме как написать драфт в GDoc, потому что есть копирайтеры, кот. надо его прислать на ревью в таком виде и т.д. А сам блог пост тебе удобнее написать в в удобном редакторе для маркдауна (в данном случае, например, используя md plugin в IDEA), чем в кривом веб-редакторе для маркдауна.

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

Прости, у меня прям сильно подгорает, не могу молчать.

В ситуации, которую ты описываешь, можно сделать что-то из этих вещей:
— копирайтеров научить пользоваться гитом, заодно станут дороже стоить на рынке труда
— техписателю/редактору освоить pandoc