Не спорю

Кажется, что вам надо попробовать понять для кого вы строите документацию. А не на каких инструментах.

У DITA большие сложности с инструментарием. Если брать DITA, нужно очень хорошо понять, что это именно то, что с чем вы хотите работать.

Иначе можно инвестировать много времени в учёбу и мало --- в результат.

Технический писатель в ГК «FIX»

Группа компаний FIX — это 15 лет успешной работы на российском и международном рынке IT. Специализируемся в сфере FinTech, электронной и мобильной коммерции, привлечении интернет-трафика.
Нам нравится внедрять и разрабатывать новые технологии, добиваться невозможного и гордиться результатами наших проектов.
Мы запустили новый FinTech проект. У нас есть задачи как для специалистов с глубокой экспертизой, так и для начинающих.

🧑🏼‍💻Обязанности:
— Описание функциональности IT-продукта как с точки зрения пользовательских сценариев, так и в технической части;
— Создание и поддержание в актуальном состоянии базы знаний проекта;
— Написание release notes для внутренних сотрудников;
— Чтение и создание технической документацией (API, инструкции, регламенты);
— Общение с командой проекта (разработчики, тестировщики, аналитики) для уточнения работы функциональности, выяснения дополнительных подробностей.

⚡️Что требуется?
— Опыт работы техническим писателем не менее 2 лет;
— Умение грамотно и быстро писать документы (технические и нетехнические);
— Умение донести до читателя технический текст простым и понятным языком;
— Грамотная письменная и устная речь;
— Знание английского языка, не ниже Intermediate;
— Готовность работать в рамках start-up проекта и выстраивать направление с нуля;
— Будет плюсом опыт работы в Fintech направлении.

✅Что мы предлагаем?
— График 5/2, гибкое начало дня, удаленный формат работы;
— Официальное трудоустройство, ДМС со стоматологией;
— Заработная плата соответствующая рынку и вашим навыкам.

#tw_wanted

📩Для отклика и по всем вопросам:
tg: @doramosova
https://kazan.hh.ru/vacancy/49764628
#вакансия #удаленка

Мм, а мне тоже интересно. DITA+Git - это уже можно считать работой в концепции Docs-as-code?

Мне казалось что этого мало

Смотрите, этот подход предполагает, что мы работаем с документацией так же, как разработчики — с программным кодом:

— Используем специальный язык разметки/программирования, который достаточно прост, чтобы человек мог писать на нём без специальных инструментов, и достаточно структурирован, чтобы машина прочитала его однозначным образом.

— Храним исходные тексты/код в системе контроля версий, организуем с её помощью командную работу.

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

Теперь давайте посмотрим на форматы, основанные на XML, вот такие как DITA:

— Язык разметки есть, но писать документацию без специального редактора очень сложно. Выше сразу порекомендовали Oxygen.
— Положить файлы в git можно, но это далеко не всё. Мержить XML крайне сложно, git diff неинформативен.
— Собирать документацию из исходников можно.

Итого, выполнено одно условие из трёх. Я думаю, что этого недостаточно. Так что нет, DITA — это не документация как код.

В разработке, кстати, та же история. Основанные на XML инструменты были популярны лет 10-20 назад, но сейчас их почти не осталось. Я помню вообще только один, это Maven, система для сборки проектов на Java. Там реально программирование на XML, декларативное и очень неудобное.

И ещё в качестве формата для конфигурации XML был очень популярен.

А сегодня системы сборки программируются на скриптовых языках (JS, Gradle, что там ещё), а конфиги пишутся в более легковесных форматах: JSON, YAML, TOML. Они тоже не идеальны, конечно. YAML так вообще ужасен. :) Но все ещё лучше, чем XML.

Вот спасибо большое за объяснение

С ворда на диту. А что попроще не смотрели? Rst, Asciidoc, markdown на худой конец.

Позволю не согласиться :) Формально  - docs-as-code. Фактически - зависит от того, как человек будет пользоваться. Можно и emacs/vim пользоваться для редактирования. И diff тоже работает :)

В кровавом ынтерпрайзе с тобой не согласны  :)

Т.е. здесь надо определить, какую среду разработки мы имеем в виду - если чистый веб, то безусловно никаких XML.. А в ынтерпрайзе это будет жить еще долго - как кобол :)

Вы считаете, что Dita не самая удачная программа для написания документов? Есть чувство, что пытаетесь отговорить

Дита как инструмент довольно массивна и плохо конвертируется во что-либо, тяжело. Точнее, тяжелее чем что-нибудь другое из списка.. Безусловно, она подойдёт в определённых условиях, но не факт. А вдруг что-то подойдёт лучше?

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

Ну и как выше сказали. Для диты нужен оксиген, он платный. А что, если можно не платить, выбрав что-то ещё? Переход на докс эз код - здорово, так зачем спешить.

Вы должны идти не от инструментов, а от требований. Например, я могу сказать, а Andrei подтвердить, что DocBook даже легче DITA в освоении. НО, это не значит, что конкретно в вашей ситуации надо использовать инструмент А, а не B. Начните со списка требований. Если хотите, может выложить их здесь, а потом коллеги подскажут,что для вас лучше.

Кстати, FYI для коллег. DITA рулит в машиностроении, где нужно четкое разделение типов создаваемого контента и когда тысячи вариантов использования. md, rst и т.п. там не покатят.

Не одной ИТ богата техническая документация.

Для диты есть бесплатная серна

Выше вспоминали её) пишут, она уже лет 10 не обновляется, и разработчик больше не существует