Постоянно приходится делать инструкции к продуктам. Условно говоря - запчасти к автомобилям.
Вопрос - чем автоматизировать бы?

Стопудов должны быть какие-то решения.

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

Нашел Dr.Explain, Help&Manual, но они чисто под документирование софта заточены - с чертежами и прочим не очень.

laTEX

опять же - что мешает сделать в том же ворде нужный шаблон (со всеми стилями и пр) и наполняй потом..?

(2) Не, ну ворд инструмент могучий, даже статические сайты в нем делали )))) Но мне автоматизировать надо. А не геморроизировать.

Ты в ворде массу инструкций в одном стиле пробовал сделать-то сам?

И LaTEX стоить оставить гикам.
Я не готов каждого ответственного за документацию обучать этой резине. Нужен простой инструмент. Типа визуального редактора статей вконтаче. Для средних умов.

кстати, по этой же причине Help&Manual не подошел, он сложный. Ща докторобъясни пробовать буду

(3) " ответственного за документацию " - ну как бы подразумевается что ответсвенный за документацию квалифицирован в области своей деятельности "выпуск документации". или не? типа маша-оператор, давай еще пусть она будет "ответственной за документацию"..? тады ой ;-)

confluence

как это выглядит у этих ребят можно посмотреть тут https://doc.maxoptra.com/docs/pages/viewpage.action?pageId=21987587

(5) нет, ответственный за документацию разбирается в предметной теме. в запчастях.

(6) он умеет pdf генерить или типа того?

а, вижу. это просто вики покрасивше. Не, не совсем то.

(1) - ну да, у него там нужны сложные химические формулы и музыка

Блин, и Dr.Explain не подошел.
Колонтитулы - на все страницы, титульного листа не понимает(колонтитул будет на всех листах, включая титульный), в стили оформления таблиц не умеет вовсе....

(4) если чего внятного найдешь - отпишись, тоже интерсено

(7) понятно. еще один "программист-бетонщик" ;-)

(11) наши все в confluence верстают. Потом оттуда выгружают в нужном виде: с названиями рисунков, с колонтитулами, с форматированием абзацев. И если результирующий документ требует корректировки, то корректируют его непосредственно в конфлюенсе, потом перевыгружают.

(14) локально стоит? мне он всю кириллицу пропустил при экспорте в pdf. пустой файл вывел

(0) э... а чертежи как бе в автокадах, компасах и прочих открытых аналогах делаются

(16) речь не о чертежах. А о сборке разнообразного контента в PDF с минимальными когнитивно-временными затратами.

(17) А почему именно ПДФ?

(14) confluence, как прочие, вообще не умеет колонтитулы делать нормальные.
Реально так и до ворда можно дойти обратно....

(18) классика жанра. Можно CDR. МОжно не знаю что.
Из чего полиграфические конторы еще печатают книжки?

(0) попробуйте Notion. Он блочного типа – инструкции на нем накидывать одно удовольствие

(20) Да, удобен. Но визуально не кастомизируется. Корпоративный стиль не выдержать....



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

(20) посмотрел - из него сохраниться во что бы то ни было не получилось
да и как то не удобно рисовать в нем что либо

(0) HTML. Он может работать как с текстом, так и с изображениями, и со стилями, и с вектором. И на нем легко программировать. Напишешь свой интерфейс, немного научишься вебу заодно, глядишь и потом устроишься куда-нибудь на зарубежную работу за евро или за баксы.

Набери в поисковике слово «ИЭТР». И рой туда. Есть и бесплатные продукты, но ограниченные функционалом. Технические руководства нормальных фирм готовятся на этих технологиях.

(23) +1 за HTML

+(24) специализированное ПО готовит технические руководства, а отображение пользователю формируется в формате НТМЛ. Но наше СПО оно корявое( имхо). Я в свою бытность искал и нашёл контору, которая решала эту проблему через плагины к експлорер. И если бы был хороший интерес у заказчика, был готов сделать сам. Трудозатраты, но это того стоило.

(24) seamatica.seaproject.ru
Боюсь у них спросить о цене ))) Как самолёт стоит стопудов. )

а, да чо спрашивать, вон калькулятор. базовая на 10 юзеров - 450 тыщ. перебор ))

(28) это для моряков. Там дорого. Есть попроще, как плагин для експлорера.

(29) Technical Guide Builder уже подешевле кстати... Надо изучить.

Technical Guide Builder оказался концептуально похож то, что надо, но реально это огромный такой комбайн, для больших предприятий.
В качестве индивидуального инструмента не пойдет, слишком сложный все равно.

Плагинов никаких связанных с ИЭТР не нашел.

По итогам, будем все-таки Confluence ставить, и настраивать стили через CSS. Он тоже не блочного типа, но пока лучшее из того, что перебрал.
Разработчикам Dr.Explain мысли про блочный редактор закинул. Пока как-то так.
Всем спасибо.

маркдаун в гите + нормальные стили для перегона в html.
greenshot для скриншотов (картинки, к сожалению, в гите блобами лежат, но тут по другому, наверное, никак)
plantuml в гите для схем

(32) это хорошо для гиков. Латекс вон уже предлагали.

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

Нужен простой WYSIWYM-редактор.

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

просто надо инструментом знать как пользоваться, а то будет как в анекдоте:
Приходит мужик в магазин с бензопилой и жалуется:
- Вот, я у Вас пилу купил - дорогую, в инструкции написано, что ей за
час можно напилить 5 кубометров дров. А я, как ни стараюсь, больше 4
кубометров за час напилить не могу!
Продавец:
- Хм, сейчас проверим (дергает за шнур-пускатель и заводит бензопилу).
Покупатель:
- Ой!!! А что это она зажужжала???

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

(34) пробую ща в Typora сделать небольшой мануал.

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

Изображения вставляются по ссылке на файл, что тоже не оч. хорошо. Но вообще да, это вариант №2, если конфлюенс не взлетит.

vs code, поделенный пополам, слева маркдаун, справа превью

https://github.com/slatedocs/slate

Я тоже за маркдаун. Просто подобрать под него wysiwyg редактор поудобней и все. Его сейчас по-моему все популярные редакторы и инструменты документирования поддерживают.
Выгружай потом в любой формат. Аскидок вот еще был/есть, но маркдаун лучше взлетел.

https://v2.docusaurus.io/

Про сплошную простыню - просто можно делать на каждый раздел по файлу

(39) вообще-то я как раз хочу уйти от wysiwyg, так как это слишком затратно.
Мне нужен wysiwyM.

(35) >на выходе получаем портал с документацией нормальный.

Задача портала не стоит. Задача стоит - получение PDF для исполнения в полиграфическом виде и для скачивания.

(31) именно этот я когда-то покупал. На нем делали иэтр для Сухого. Купил 10 лицензий, обучился. Сделали несколько руководств. Оказался очень проблемным с точки зренияпривязки к другой отрасли, да и эксплуатации. Потом прошёл слух, что и Сухой от него отказался. Так что не рекомендую. Я стал искать другую платформу, моряков отказал-дорого и много темных мест. Натолкнулся на плагин, вот только сейчас все поуничтожал, подсказать не смогу, надо заново искать.

для пдф latex :)
маркдаун тоже можно, конечно

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

(46) чего скрывать, нормально доки в ворде делать не умею и я. Всё разъезжается, стили постоянно надо править после копипаста, и проч. Адская работа.
Тут применимы законы Паркинсона, если что-то может пойти не так - оно обязательно пойдет. Поэтому и нужен инструмент, где ничего не так пойти не может.

(0)
Конфлюенсом пользуемся, очень нравится. Но только в онлайне, в PDF не выгружаем.
Однако ж в PDF можно и средствами браузера сохранять, если сам конфлюенс не умеет... если это подходит конечно... сам не пробовал.

(48) Да, была такая мысль, пдф браузером делать. Но. браузер не умеет работать с номерами страниц, поэтому оглавление нормальное не получится.

(48) конфлюенс умеет. у него очень бедненько в плане инструментов редактирования колонтитулов, но это мы попробуем побороть через CSS.

(42) Ну дык маркдаун - это как раз про это. Это максимально простой и "нативный" язык разметки простых документов.
Не нравится гиковость текстового wysiwym - для него можно найти и плюшевые wysiwym-редакторы. Хотя он создавался как раз из расчета, чтобы можно было обходиться без них и работать с плоским текстом.
wysiwyg в связке с маркдауном - это просто предпросмотр результата разметки с конкретной "шкуркой".

(49) скорее всего и с маркдауном пролетите. а вот латекс да, запросто сможет.

но нафига в современном мире доки в виде пдф - не совсем понятно. счас даже к стиралкам инструкции онлайн.

Для маркдауна попробуйте typora.io
Но всякие "издательские" хитрости типа колонтитулов в pdf - это уже настраивается заголовками для конкретных конвертеров, которые такое умеют и тому подобными финтами.
Потому что это уже не вопрос схемы документа, а вопрос его представления.

Примечательно, что вся справка/документация по typora написана на маркдауне и отображается ей точно так же как и любые другие маркдаун документы, с которыми она работает. То есть можно в нее же подглядывать как в пример оформления документации. Фишка typora в том, что они очень удобно и прикольно совмещают одновременно маркдаун-разметку и пресловутый wysiwyg.

А почему Wikia не подошла?

(53) Вопрос к законодателям. Законы о защите прав потребителей и удаленной торговле. Ну и в самом деле, если чел живет в деревне, где инет по талонам - что теперь, лишать его инструкции?

Всё в целом взлетело. Даже PDF генерит. Не удалось конечно все задумки реализовать, но в общем - летит.

Есть спецы у кого по этому конфлюенсу, кому подхалтурить надо? Кое-какие работы все же хотелось заказать бы, только ума не дам, как их искать-то вообще. на фрилансе их вроде нет, или не там ищу.