Коллеги, поясните пожалуйста касательно требований знать языки программирования на уровне джуна хотя бы. Не понимаю, как в нашей практике это использовать?  Ранее мне приходилось читать небольшие фрагменты кода на С/С++, т.к. разработчикам именно в таком виде было проще выдавать информацию, но не представляю, сколько ресурсов надо на копание в исходниках большой программы

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

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

Если вам надо прям полностью изучать исходники программы, которую вы описываете, то это означает, что плохо поставлены процессы в команде

Мне пригождалось дважды и оба раза было связано с разработкой документации для целевой аудитории - разработчиков.
Первый вариант - нужно самостоятельно составить удобную и достаточную документацию на продукт, предназанченный для разработчиков. Имея лишь записи из коммитов/пуш-реквестов, ну иногда еще RFC/issues. Надо одеться в шкуру разработчика и пройти его путь, чтобы найти и описать все подводные камни.
Второй вариант - реально приходжилось лезть в исходный код, находить список параметров вызова функций в API и описывать их, исходя из комментариев в коде и самого кода иногда.

Ну плюс еще иногда приходится немного самостоятельно писать на python или на lua для разработки Tutorial'ов или примеров для основной документации, либо для автоматизации сборки документации из исходников.

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

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

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

Чем раньше приступать к описанию задачи, тем лучше: разработчики помнят что они делали и могут подсказать техпису разные подробности.

Всем привет! У меня на работе скоро (надеюсь) грядет радостное событие: будем переделывать дизайн нашего док. сайта. Как раз сейчас пытаемся сформировать список разных компонентов/хотелок, которые могут быть нужны на сайте с документацией. Например, info/tip/note/warning блоки, expand/collapse блок, tabs. Есть идея сделать отдельные компоненты для глоссария и Q&A.
* Какие ещё компоненты кажутся вам важными и нужными для док. сайта?
* Если бы вы составляли список хотелок для своего док. сайта, что бы туда включили?
* Можете поделиться примерами любимых компонентов/хотелок на других док. сайтах?

это работает, если у проекта разработки адекватный менеджер. В противном случае процесс документирования превратится в бесконечное переписывание и переделывание вслед за измененными\отмененными фичами продукта. В таком случае лучше как раз приступать к документированию после code freeze (хотя даже его особо эффективные PMы умудряются «размораживать» в самый неожиданный момент)

У нас еще есть пометка "устаревшее", т.к. кое-где стоит устаревшая версия программы, поэтому из хелпа куски не выпиливаются. Но чтобы не смущать тех, у кого новая версия - ставим пометку.
Есть еще отдельные стили для примеров, для полезных ссылок в конце каждой статьи.
И в идеале еще нужен стиль для элементов интерфейса (название поля, кнопки и т.п.). Т.е. должна быть возможность задать стиль не для параграфа, а для куска текста (<span>).

Реальный code freeze кто-нибудь делает? Имхо всегда feature freeze с исправлением багов.
Ну кроме сертификации - там есть актированный отбор экземпляра со снятием контрольных сумм.

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

если техпис "щупает" то, что описывает, то он вполне может найти баги, предложить более человеческий UX и т.д. Исправлять баги можно всегда, а вот переделывать UI/UX точно лучше до код-фриза.

> feature freeze с исправлением багов.
хотя бы так, да) но мне приходилось работать на проектах, где и такого не было, фичи могли выкидывать\вкидывать прямо перед датой технического релиза, а то и после) но это, конечно, уже не вопрос документирования, а в целом процессов в компании

Можно добавить компонент для связи с читателем. Например, возможность написать об ошибке в доке, оценка "Полезна статья или нет?", комментарии

с этим никто и не спорит. Если есть возможность щупать самую актуальную версию, это прекрасно для всех. Но в сложных продуктах техпис не всегда может прощупать достаточно глубоко, чтобы заметить какое-то изменение в поведении продукта, о котором команда разработки не донесла до техписа как следует (или вообще забыла донести, несмотря на каждодневные статус-митинги)

возможность ставить метки/теги

комментарии — ворота для спама 🙂
отзывы — вещь довольно необъективная. Положительные отзывы не пишут почти никогда, отрицательные — гораздо чаще и редко по делу. То есть КПД от такой обратной связи довольно низкий. Я несколько лет работал в команде по управлению онлайн базой знаний, мы эти штуки все проходили.