Size: a a a

technicalwriters

2020 December 28

rK

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

СФ

Семён Факторович... in technicalwriters
Bobba Fett
Под альтруистом понимается сотрудник, который бесплатно занимается смежными вещами. Например, техпис, который заодного ПМит или бизнес аналистит или докопсит или тест планы пишет или с текстами в интерфейсах помогает. Демпингующий он потому что снижает стоимость тех, кто и готов бы совмещать, но не готов это делать бесплатно. Поэтому присутствие альтруистов на “рыночке” негативно сказывается на общей средней стоимости техписов.

Вам такие нужны? Или лучше пусть свои основные обязанности выполняет и с помощью своей никуда не лезет?

Если нужны, то вы готовы их поощрять финансово или это их дело?
Я помню этот хороший вопрос и хорошо над ним подумал.

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

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

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

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

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

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

СФ

Семён Факторович... in technicalwriters
Семён Факторович
Усталость забыта, колышется чат!

Снова пятница, снова разговор за зарплаты и скиллсеты.

Товарищи дискутирующие, а может вам, чисто для разнообразия, перестать смотреть среднюю температуру по больнице на hh и строить теоретические измышления «в вакууме» относительно нужд работодателей? Которую неделю одно и то же.

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

И ребят из JetBrains можно сюда позвать, я лично знаком со всей командой техписов Котлина.

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

SM

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

SR

Stas Rychkov in technicalwriters
RFC что ли писать? Там как раз EBNF.
источник

SM

Semantic Massive in technicalwriters
Stas Rychkov
RFC что ли писать? Там как раз EBNF.
Да, практически его
источник

BF

Bobba Fett in technicalwriters
Семён Факторович
Я помню этот хороший вопрос и хорошо над ним подумал.

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

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

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

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

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

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

AB

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

H

Hartmann in technicalwriters
Arina Ballerina
Кто-нибудь видел рейтинг сайтов с технической документацией для разработчиков, который выпустило какое-нибудь уважаемое издание или комьюнити. Кажется должно существовать что-то вроде 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/ “
источник

AB

Arina Ballerina in technicalwriters
Спасибо! Тоже результат)
источник

EN

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

AB

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

DS

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

СФ

Семён Факторович... in technicalwriters
источник

H

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

СФ

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

СФ

Семён Факторович... in technicalwriters
вот так еще можно, да:)
источник

H

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

FM

Fox Mulder in technicalwriters
источник

ЕЕ

Е Е in technicalwriters
Семён Факторович
​​Угадайте, что имели в виду авторы вакансии?
Пишите в @docsascode.
Мерзавец - это самый маленький объем водки, который продают.
источник