Кто-нибудь сталкивался с ситуацией запрета открыто распространять документацию к продукту? Именно пользовательской документации. Обосновывая это возможностью конкурентов украсть фичи, сделать похожее и так далее. Документация вся в ворде, распространяется только для клиентов в PDF.
Началось всё с того, что я предложил перевести её в reStructuredText и генерить сайт через readthedocs, храня в гитхабе, затем предлагал самим генерить сайт через sphinx и хостить где хотят. В обоих случаях перспектива открытого хранения доки была воспринята как опасное явление, влекущее за собой опасность воровства идей, фич и так далее. Предложение не поддержалось.
Сейчас я занимаюсь созданием видеоматериалов по документации, по сути зачитываю документацию, но на фоне соответствующих разделов/окон, то есть показываю всё то, о чем говорю, и добавляю кейсы использования. И это была не моя инициатива, была задача на создания такого рода обучающих видеоматериалов от начальства. Но теперь опять же всплыла тема с опасностью распространения этих материалов, ибо я говорю давайте на ютуб зальем в плэйлист с доступом по ссылке, будем обновлять/добавлять видосы, комментарии от юзеров читать, а мне опять говорят, что на ютубе конкуренты посмотрят и украдут. В качестве площадки для распространения предложили что-то вроде stepik.org, что в моем понимании не защитит от просмотра конкурентами, но остановит от просмотра пользователями, которые не захотят ради этого регаться на непонятных площадках.
Лично я не понимаю, зачем вообще создавать документацию, если её нельзя распространять, и тем более если она в видеоформате. Сделано уже более 10 роликов в среднем по 10 минут, несколько из них уже устарели и полностью неактуальны, но и те, которыми можно пользоваться - никто не видел, лежат себе в кофлюенсе, отсмотренные только начальством)

Я помню этот хороший вопрос и хорошо над ним подумал.

Нет, на мой взгляд, «альтруисты» такого толка не размывают рынок. Демпинга (в словарном определении этого термина) тут тоже нет.

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

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

2. Ценообразование техписательских зарплат в целом тоже определяется не пойми чем. Поскольку рынок мал (см. п.1), нет достоверной статистики, средних зарплат, срезов по профилям скиллов и регионам. А раз этого нет, то компании зачастую определяют зарплатные вилки своих техписательских вакансий только из внутренних соображений. Соображения эти могут быть иногда очень своеобразными («мы выбили из финотдела только 40к/мес, больше никак не дадут, поэтому давайте попробуем найти хоть кого-нибудь на эти деньги»). Понятно, что такая фигня есть и для вакансий разработчиков, но там более широкий рынок сглаживает такие редкие странности.

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

3. Нужны ли лично мне «разносторонние» техписатели, умеющие и в системную аналитику, и в DocOps, и в тексты в интерфейсах? Очень нужны, бизнес любит многофункциональных людей:) И да, мы готовы платить им больше. Но таких исчезающе мало, мы даже искать бросили. Гораздо проще выделить малопересекающиеся профессиональные профили (пользовательская документация, документация API, DocOps) и искать людей на них отдельно.

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

Привет, кто умеет работать с такими штуками как: Иерархия Хомского и Форма Бэкуса — Наура пишите в ЛС, есть удаленная работа.

RFC что ли писать? Там как раз EBNF.

Да, практически его

Благодарю!

Кто-нибудь видел рейтинг сайтов с технической документацией для разработчиков, который выпустило какое-нибудь уважаемое издание или комьюнити. Кажется должно существовать что-то вроде forbes 50, мишленовских здвезд для ресторанов, ну или хотя-бы конкурс, в котором победил digitalocean. Пробовала искать, но гугл мою мысль не понимает.

Видимо, потому, что таких рейтингов нет.

Максимум, что попадается по подобного рода запросам — это или описание подходов, инструментов, или пассажи наподобие этого

“Discover what choices the writers made (implictly) and what works for you w.r.t. structure, clarity, completeness, conciseness. In your case, look for documentation of other (web) frameworks with a large audience, for example:
– Django: https://docs.djangoproject.com/en/1.7/
– Symfony: http://symfony.com/doc/current/book/index.html
– Rails: http://guides.rubyonrails.org/ and http://api.rubyonrails.org/ “

Спасибо! Тоже результат)

О, это прямо в точку, спасибо огромное!

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

Резюме в таком стиле составить. Завидный специалист выдйет.

​​Угадайте, что имели в виду авторы вакансии?
Пишите в @docsascode.

вот так еще можно, да:)

Главное — дружелюбие, чтобы с благими намерениями.

Мерзавец - это самый маленький объем водки, который продают.