Меню
Оставить заявку
Статьи
Свежевыжатые соки для технических писателей

Выбор системы разработки программной и технической документации

Поиск  Пользователи  Правила  Войти
Форум » Лаборатория технического писателя » "Единый источник" документации

Внимание! У нас сбои с почтовым сервером! Если не пришло письмо о регистрации или смене пароля напишите нам на info@techwriters.ru! 
@twriters obmen_soobsheniyami.pngчат для технических писателей в Telegram

 Зарегистрируйтесь
   RSS
Выбор системы разработки программной и технической документации, Есть требования к системе, нужна помощь с подбором ПО.
 
#1
Мне нравится1
22.01.2016 17:17:03
Нужна помощь пользователей форума в выборе системы разработки программной и технической документации (читал, похожие темы здесь, но набор требований там был другой, поэтому изучаю возможности разных систем и их комплектаций).

Дано
  1. На предприятии используются 2 программы для поддержки документации: H&M (лицензия) – для ПО, LaTeх (в виде TeXLive + TeXStudio) – для полного пакета документов по ГОСТу для большой номенклатуры «железа»;
  2. Команда: несколько разработчиков, один техпис (H&M знает хорошо, LaTeх – начальные знания достаточные для выпуска документов по ГОСТу), он же будет выполнять  управление системой. Уровень познаний техписа в программировании – написание автоматизированных тестов выше среднего уровня для ПО, Web-интефейсов (Selenium IDE, AutoIt), желание развиваться есть;
  3. Используемая ОС – Windows.
Требования к системе
  1. Принцип единого источника (желательно также, чтобы при изменении данных в источнике все связанные документы формировались бы автоматом или по одному-двум кликам);
  2. Единая система для всей документации (как можно меньше "костылей", которые будет трудно автоматизировать), может состоять из нескольких программных продуктов (подсистем);
  3. Легкий интерфейс для первичного редактирования текста, который будет выполняться разработчиками ПО, «железа» (желательно WYSIWYG-интерфейс, но не обязательно);
  4. Возможность компилирования документов в формате pdf по ГОСТу!!! (рамочки, штампики, нумерация элементов документов, корректное разбиение многостраничных  таблиц и т.д.) – не видел соответствующих шаблонов в H&M (нумерацию элементов использую);
  5. Возможность использования в тексте ссылок на элементы документа типа «см. рис.3, см. п. 1.1» с автоматическим изменением нумерации, а также гиперссылок (clickable);
  6. Конвертирование информации в форматы web-документов html, wiki (планируется создание базы знаний для клиентов на основе единого источника) и автоматическое обновление данной информации на сайте (в базе знаний);
  7. Возможность вызова контекстной справки (для chm, webbased);
  8. Поддержка перехода на другие языки единого источника (выпуск документации на другом языке).
Еще один вопрос
Специ по LaTex подскажите, можно ли прикрутить к нему недостающие возможности из указанных требований? Импортировать, при переходе на другую систему, придется много документов.
 
 
Страницы: Пред. 1 2
Ответы
 
#26
Мне нравится0
10.02.2016 20:42:47
Цитата
Виктор Фигурнов написал:

Цитата
Текрайтер из Питера   написал:
Насколько я понимаю, оглавление динамически изменяется только при использовании GUI.
Это не так. Во Flare совершенно другая концепция оглавлений, чем та, к которой вы привыкли. Более сложная.
Во Flare можно создавать оглавления автоматически. Можно вручную. Можно создавать  title  для топика по оглавлению.
Можно использовать несколько оглавлений в одном проекте. Все зависит от задач. Оглавления бывают разных типов.. И т.д.

Описание использования оглавлений во Flare - 184 страницы
http://docs.madcapsoftware.com/FlareV11/FlareTablesOfContentsGuide.pdf
Я осознаю, что Flare позволяет делать разные вещи, в т.ч. в части обновлений. НО, он позволяет делать это только с помощью Flare (т.е. обычного .exe в каком-либо виде - GUI или командной строки, неважно). А я говорил немного о другом... Я имел в виду, что если вы измените просто текст. Т.е. возьмете проект Flare из VCS (или какой-либо файл), откроете его в текстовом редакторе, измените его, а потом сделаете commit, то по сути ничего не изменится. Вам надо изменять его внутри Flare какие-либо образом.

Впрочем, я думаю, что это уже некоторый оффтопик первоначальной темы.
 
 
 
#27
Мне нравится0
11.02.2016 08:17:57
Цитата
Текрайтер из Питера написал:
Я осознаю, что Flare позволяет делать разные вещи, в т.ч. в части обновлений. НО, он позволяет делать это только с помощью Flare (т.е. обычного .exe в каком-либо виде - GUI или командной строки, неважно). А я говорил немного о другом... Я имел в виду, что если вы измените просто текст. Т.е. возьмете проект Flare из VCS (или какой-либо файл), откроете его в текстовом редакторе, измените его, а потом сделаете commit, то по сути ничего не изменится. Вам надо изменять его внутри Flare какие-либо образом.
Скорее всего, ваши высказывания отражают предубеждения, а не реальный опыт работы с обсуждаемым продуктом.

У меня основной режим работы с проектами Flare - это редактирование основных файлов проекта (топиков, стилей, оглавлений, глоссариев и др.) не в GUI, а в текстовом редакторе, обычно это Notepad++ или Sublime.
Мне так удобнее. Т.к. цветовая подсветка лучше выделяет логическую структуру документа, а шаблоны для основных конструкций я назначил на комбинации клавиш.

Но некоторые вещи удобнее делать в GUI.
Например, при переименовании или  перемещении файла топика или рисунка в GUI Flare автоматически находит все ссылки на файл, выводит список этих ссылок и предлагает их скорректировать.
И при утвердительном ответе автоматически исправляет все эти ссылки.
Многие вспомогательные файлы проекта Flare тоже удобнее  редактировать в GUI.
Исправлять ошибки в файлах проекта тоже обычно удобнее в GUI, так там наглядно показывается, где ошибка и в чем она состоит, и проще ее тут же и исправить.

Динамические обновления, о которых вы пишете, во Flare вообще отсутствуют. Можно сказать, что проект Flare это не интерпретируемая, а компилируемая система объектов.
Вроде проекта программы на языке C++. Там тоже вы можете вносить любые изменения в тексты программы, и "по сути ничего не изменится".
Чтобы получить результат, надо запустить сборку (build) .

В процессе сборки (build) некоторые элементы выходных документов формируются не только по локальному контексту, а с учетом всего содержимого проекта. Это, например, оглавления, индексы, перекрестные ссылки.
 
 
 
#28
Мне нравится0
12.04.2016 08:24:36
Всем добрый день!
Подскажите, какие программы используете при работе с единым источником?
Нашла, что можно создавать документы в XMLmind, а компилировать в DITA.
Возможно, я что-то не совсем верно понимаю в технологии единого источника.
Интересует возможность компиляции документов из отдельных глав/страниц, при этом должна быть автоматическая нумерация глав/рисунков и т.д. (одна и та же глава будет иметь разный номер в разных документах).
Имею опыт работы с dr.explain, мне она показался неудобен тем, что при наличии большого документа с множеством страниц, из которого создаются более мелкие документы, надо каждый раз включать/выключать печатаемые/непечатаемые страницы. Т.е. нет такого, чтобы один раз прописать, что в этом руководстве есть только эти разделы, в другом - только эти.
 
 
 
#29
Мне нравится0
12.04.2016 09:29:46
Цитата
ПчОльkа написал:
Всем добрый день!
Подскажите, какие программы используете при работе с единым источником?
Посмотрите программу Syntext Serna, может подойдёт.
 
 
 
#30
Мне нравится0
12.04.2016 11:47:42
Цитата
Ranaloc написал:
Посмотрите программу Syntext Serna, может подойдёт.
Спасибо за совет. Не могу найти официальный сайт разработчиков. Syntext.com на алиэкспресс перебрасывает.
И это платная программа? Не могу найти ни цены, ни тех.поддержки. Подскажите, где найти представителей?
Изменено: ПчОльkа - 12.04.2016 11:52:37
 
 
 
#31
Мне нравится0
12.04.2016 12:32:18
Цитата
ПчОльkа написал:
Спасибо за совет. Не могу найти официальный сайт разработчиков. Syntext.com на алиэкспресс перебрасывает.
И это платная программа? Не могу найти ни цены, ни тех.поддержки. Подскажите, где найти представителей?
На википедии пишут: XML редактор Syntext Serna доступен в двух изданиях: Serna Enterprise и Serna Free Open Source. Serna Enterprise — лицензированный коммерческий программный продукт с возможностью бесплатного ознакомления с пробной версией в течение 30 дней. Serna Free Open Source — бесплатный редактор XML с открытым кодом.

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

Почитайте статью https://habrahabr.ru/post/112371/ Автор пишет, что когда-то Syntext Serna была закрытым и платным продуктом. Там ещё и альтернативы предлагают. Хотя вот ссылки его ведут (по крайней мере у меня) на пустую страницу компании-разработчика. Может у кого-то эти страницы наполнены смыслом?

Создаётся впечатление, что сейчас программа бесплатна, так что смело штурмуйте торренты.
 
 
 
#32
Мне нравится0
12.04.2016 15:09:06
Цитата
Ranaloc написал:
Создаётся впечатление, что сейчас программа бесплатна, так что смело штурмуйте торренты.
Правообладатель (Flatirons Solutions) прекратил распространение этой программы в 2013 г.. И платной, и бесплатной версии.
Законных способов стать новым пользователем этой программы, по-видимому, не имеется.
Техподдержки и новых версий также ждать не приходится.
 
 
 
#33
Мне нравится0
12.04.2016 15:11:38
Цитата
Виктор Фигурнов написал:
Правообладатель (Flatirons Solutions) прекратил распространение этой программы в 2013 г.. И платной, и бесплатной версии.
Законных способов стать новым пользователем этой программы, по-видимому, не имеется.
Техподдержки и новых версий также ждать не приходится.
Ого.. Жаль, хорошая программа. Значит будем пиратствовать на свой страх и риск  *writing*
 
 
 
#34
Мне нравится0
13.04.2016 15:56:46
Цитата
ПчОльkа написал:
Всем добрый день!
Подскажите, какие программы используете при работе с единым источником?
Нашла, что можно создавать документы в XMLmind, а компилировать в DITA.
Возможно, я что-то не совсем верно понимаю в технологии единого источника.
Интересует возможность компиляции документов из отдельных глав/страниц, при этом должна быть автоматическая нумерация глав/рисунков и т.д. (одна и та же глава будет иметь разный номер в разных документах).
Имею опыт работы с dr.explain, мне она показался неудобен тем, что при наличии большого документа с множеством страниц, из которого создаются более мелкие документы, надо каждый раз включать/выключать печатаемые/непечатаемые страницы. Т.е. нет такого, чтобы один раз прописать, что в этом руководстве есть только эти разделы, в другом - только эти.

Вы должны понимать преимущества и недостатки работы с единым источником.

Сначала ответьте себе на вопрос: какой тип софта  (или не софта) вы собираетесь документировать? Например, если у вам типичное Windows приложение и вам надо просто документироваьт GUI, но единый источник вам будет тяжеловат. В таком случае вам хорошо подойдет Flare (по нему Виктор Фигурнов подскажет более подробно).

Единый источник имеет смысл только при большом количестве продуктов, многоплатформенности, вариативности как "каналов публикации", так и контента.
 
 
 
Страницы: Пред. 1 2
Читают тему

©2005- 2021 «TechWriters.ru: Все для технического писателя и разработки технической документации»


info@techwriters.ru
-->
г.Москва, Большая Спасская 10/1
Рейтинг@Mail.ru