Вот тут ещё с описанием апи-портала

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

Документация в виде блогов? Неплохо смотрится на самом деле

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

кто вам пишет техническую обвзяку? (настраивает ci/cd, yaml. front etc)

Нам компания выделила одного фронтендера, одного девопса и одного тестировщика - ямл лежит в соседнем репозитории, и добавляется к маркдаун файлу специальными тегами

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

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

Норм на самом деле

Тут главное - дать больше возможностей и коллеги сами выбирают, как им удобнее доносить информацию

И при этом многие заинтересованы в документации - наличие справки в открытом доступе реально влияет на продажи продукта

* да, мы сели с аналитиками и посчитали

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

В Яндексе (и конкретно в Облаке) ценят технических писателей и понимают важность документации. Команда замечательная, задач много, они разнообразные и интересные. Не все процессы пока выстроены (и можно будет участвовать в построении). Есть задачи, которые не связаны напрямую с документацией —  например, вычитываем практически все продуктовые тексты.

Москва или Санкт-Петербург, Yandex.Cloud #wanted_tw
Ищем человека с релевантным опытом (техническая документация для разработчиков, описание API, SDK, сложных технологий) и отличным русским языком. Вакансия и небольшое тестовое на сайте.

Если есть вопросы, можно задать их прямо мне.

Добрый день, коллеги. Вопрос на тему портфолио. Ранее много обсуждалось как можно его сделать, если все ваши проекты попадают под NDA. Вопрос: как вы отнесётесь к кандидату, если он показывает в качестве примеров свои статьи технического характера, опубликованные в научных журналах?

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

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

привет. у нас есть какие-нибудь стандарты индустрии в документировании? например, используется docs-as-code, есть стайлгайд, процессы автоматизированы по максимуму (создание, публикация, тестирование, локализация), Swagger как спека для API документации и т.д.

Крутяк, The Joel Test, но для документации. Надо бы придумать такой!