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

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

в яндексе мы сделали крутой конвейер, когда на входе была дита, md, rst, wiki и другие форматы, а выход был единообразным
по-моему, мы рассказывали об этом на последних Гипербатонах

да, но нет
от реализации зависит

Отдали часть документации на аутсорс.
Получаем <s> "документ" </s>.

Да, помню с Лешей Мироновым беседовал по этой схеме. У меня в конце мозги плавились. А потом Лёша полез в ant для того, чтобы показать как его параллелить..

В Сбере круто. Это правда.
Документация нужна. И это правда.

По поводу Гипербатонов. Свято место пусто не бывает :)

Ну правильно же написано, то. Надо выполнить ОС семейства ..
Как получить шаг 1. если не выполнить до этого шаг * )))

У нас боль - docx. И чем глубже, тем больнее. Так тяжело его кастомазить для цепочки.

так а зачем исходники в docx
если docx зачем-то нужен, то его лучше генерить из других исходников каких-то, а работать в более удобном окружении

Docx нужен заказчику.
Мы пишем в asciidoc, далее через gradle+фреймворк docToolchain {который подгружает pandoc} и reference-doc формируем нужный docx.
Помимо проблем с самим docx, который внутри кривой, выявились проблемы и с gradle, а точнее с task внутри джобы. Этот таск, тысяча ежей ему в руку, не хочет делать множественное  трансглютирование {конвертацию пакета файлов}.

А зачем? Документацию разные команды предпочитали вести в разных форматах? Но при этом нужно было всё это одинаково публиковать?

Не столько предпочитали, сколько разные инструменты разработки были целесообразны разным командам.
Научить СКВ и дите всех невозможно.
Писателям удобна дита и единый источник
Разработчикам md и rst удобнее
Техподдержке и менеджерам удобнее всего wiki
А пользователю все равно, в чем готовится документация, ему нужен единый внешний вид всех страниц документа.

Товарищи, подскажите! Есть ли какие-нибудь хорошие книги или статьи про то, как писать инструкции? Что считается критерием хорошей инструкции, на что стоит обращать внимание при ее написании.

Я как-то обещал про совсем уж техписную базу не писать, но сегодня исключение, зато какое! Это ультимативная точка в вопросе “как мне начать, что учить, какой курс пройти и где бы этому всему-то структурировано научиться?”

Делюсь с вами офигенным “Учебным пособием по техническому письму” под авторством Филипа Тори. Филип — преподаватель с большим стажем, ныне в отставке, от того и раздает свой учебный материал.

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

Краткое оглавление:

📍 What is – or isn’t – ‘Plain English’?
📍 Average Sentence Length?
📍 ACTIVE or PASSIVE voice – what’s the difference?
📍 Writing Style
📍 Jargon and Acronyms
📍 Instructions and Procedures
📍 Bullet Point lists and Punctuation
📍 Planning what to write
📍 Structuring your Document

Каждый пункт там состоит из нескольких подпунктов, да и самих разделов там ого-го.

Это 150-страничная книга с упражнениями, вопросами и ответами, предполагается, что вы ее распечатаете и будете заниматься как студенты. Я предлагаю заниматься этим в основном в первом модуле, а остальное воспринимать как теорию. Теория в книге довольно таки качественная, за исключением советов по всяким программкам и раздела про MS Word, это все-таки немного устарело и лучше бы это все не впитывать в себя. Но если вы совсем новичок, можно послушать и советов про Word.

Enjoy 🎉

⬇️ Скачать: Technical Authoring Course Training Manual (PDF)

Благодарю!

можно посмотреть в _Robinson - Writing and Designing Manuals and Warnings (2020)_

Добрый день, пропустила часть, подскажите, почему гипербатонов не будет?

Спасибо.