Разработка технической документации и технические писатели Технические писатели и разработка технической документации технические писатели в Телеграм 

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1
RSS
Выбор системы. Выход webhelp/pdf
 
Коллеги, позвольте создать новую тему, так как много похожих веток с годами на форуме устарели.

Посоветуйте, пожалуйста, систему (один продукт или набор) под такие исходные данные:
- конечная документация - пользовательская
- команда разработчиков (5-10 человек) программного продукта, они же будущие писатели + 2-3 сотрудника, выступающих еще в роли выпускающих редакторов.
- необходима возможность рецензирования. Здесь возможны варианты. Например: писатель правит текст, редактор видит что это правка (корректирует при необходимости) и выпускает "в свет". Или: писатель делает draft-лист, редактор видит что появился draft-лист и Copy&Past его с корректировками в конечный документ. Ну или как-то еще.
- возможность нормальной(!) совместной работы. То есть, либо топик/раздел/файл/категория (и т.д.) заблокированы при правке одним человеком вообще, например, или открывается в режиме ридонли или что-то в этом роде. Типа SVN-а. :)
- все редактирование хочется выполнять в формате максимально приближенном к WYSIWYG. То есть, правки в чистом виде wiki, где картику надо сначала залить на сервер, потом ручками набить тег и путь к картинке и в итоге потратить на вставку одной картинки одну минуту.... нежелательны. То есть вопрос не удобства визуализации в общепринятом формате WYSIWYG, а скорости работы. :)
- конечный формат: web с возможностью поиска по всему пакету и pdf.
- система или бесплатная или недорогая. Последний критерий... ну 30 000 - 50 000. Руб. Российских. :)

Заранее спасибо!

P.s. сечас документация есть в word, но устаревшая от 3 до 6 месяцев, к сожалению. Поэтому её будем и переносить и актуализировать. Кстати, разброс всего и всех в word-файлах сейчас не позволяет и нам самим (разработчикам) найти... "А где это у нас описано?"-"А Х... его знает". :)
 
DITA Open Toolkit (sourceforge.net/projects/dita-ot/)

Все ваши требования выполняет, плюс есть еще ряд преимуществ.
100% бесплатно всё, что с ней связанно, включая редакторы.
 
Цитата
DITA Open Toolkit (http://sourceforge.net/projects/dita-ot/)Все ваши требования выполняет, плюс есть еще ряд преимуществ.
100% бесплатно всё, что с ней связанно, включая редакторы.
Плюс ADVANCED в ней неплохой специалист и поможет если что)  :D  Верно?
 
Цитата
в ней неплохой специалист и поможет если что)  :D  Верно?
Верно, но при наличии времени на это  :)  . Поможем, чем можем.
 
Коллеги, разобрал где и что лежит и как работает в общем, но есть дальнейшие концептуальные вопросы..... Help.  :)  

Цитата
- необходима возможность рецензирования. Здесь возможны варианты. Например: писатель правит текст, редактор видит что это правка (корректирует при необходимости) и выпускает "в свет". Или: писатель делает draft-лист, редактор видит что появился draft-лист и Copy&Past его с корректировками в конечный документ. Ну или как-то еще.
Каким образом можно сделать такое "рецензирование", порекомендуйте, пожалуйста, схему (подход)?

Цитата

- возможность нормальной(!) совместной работы. То есть, либо топик/раздел/файл/категория (и т.д.) заблокированы при правке одним человеком вообще, например, или открывается в режиме ридонли или что-то в этом роде. Типа SVN-а.  :)  
Правильно ли я понимаю, что заталкиваем все в SVN и типа радуемся жизни?

Если да, то каким образом мне, как писателю, проще сопоставить раздел файлу-топику? То есть, я хочу поправить топик "Настройка плагина Idiom", как мне найти в каком файле необходимо сделать правки текста? Лезть каждый раз в карту?
<-Ага, это я понял, XMLMind позволяет открыв карту проваливаться по ссылкам, гуд. Почему-то в Серне и в XMLPad я такого не нашел.... Ну да Бог с ним, редакторы еще поковыряем. Тем не менее остается вопрос совместной работы.... Надеюсь на помощь и Ваши предложения.


ps. Модератору: перенесите эту тему в подраздел по DITA, плиз.
 
XMLMind отличный редактор. Не стоит от него отказываться.

Цитата
- необходима возможность рецензирования. Здесь возможны варианты. Например: писатель правит текст, редактор видит что это правка (корректирует при необходимости) и выпускает "в свет". Или: писатель делает draft-лист, редактор видит что появился draft-лист и Copy&Past его с корректировками в конечный документ. Ну или как-то еще.
Цитата
- возможность нормальной(!) совместной работы. То есть, либо топик/раздел/файл/категория (и т.д.) заблокированы при правке одним человеком вообще, например, или открывается в режиме ридонли или что-то в этом роде. Типа SVN-а.  :)
По поводу драфт-листов и правок редакторов. Есть программа CODE REVIEW от компании Atlassian. Программа состоит из двух частей: Клиент и сервер. Суть такая:

Серверная часть интегрируется с SVN (GIT, Mercurial и т.п.) на сервере.

Каждый автор (писатель) открывает клиентскую часть, через которую подгружает свеженаписанный xml-файл или несколько. Программа автоматически блокирует возможность коммита в репозиторий, пока не завершится проверка редактором или другим пользователем (корректором, старшим, тестировщиком или программистом).

После завершения правок (*), клиентская часть "отправляет" файл на сервер, где он становится доступным для просмотра или правок другим пользователями ( в это время он все еще залочен в SVN).
Программа позволяет отправлять файл как "в никуда", так и конкретному пользователю (-лям) на проверку.

После правок или проверки, файл может быть либо возвращен автору, либо закоммичен в SVN напрямую.

Есть еще фишка - поставить метку так, что автор никак не сможет закоммитить файл, пока он не будет проверен повторно. Т.е. есть несколько вариантов защиты от раздолбайства.

* - правки могут быть либо непосредственно в файле через клиентскую часть, либо составлением комментариев для автора или когото еще. В общем функций дофига и главное - все понятно.
 
понятно, что ничего не понятно ))))
 
вот есть несколько комментов [code:ae35q8eq]http://habrahabr.ru/qa/15353/[/code:ae35q8eq]. а также ссылки на аналоги.
 
...целый день сегодня читал инет. Так как у нас используется TFS, то пытаюсь придумать как прикрутить подход code review к нему. В любом случае, изучив code review и почитав про инструменты у меня вопрос на который я пока не нашел ответ (читал в соседних ветках устаревшие обсуждения дорогущих cms для dita, но это же не вариант): если мне клиент говорит и я вижу в конечном pdf (например) ошибку, то как мне найти/поправить эту ошибку в исходном файле-топике?

Я пока вижу один вариант, котрый мне очень не нравится (потому что придется бегать два раза между двумя инструментами):
1. Идем в svn/tfs, копируем весь проект себе.
2. Открываем в XMLMind карту, по карте проваливаемся к нужному файлу-топику (так как именно в карте есть разбивка по разделам (topichead)).
3. Возвращаемся в svn и забираем файл на редактирование
4. Открываем XMLMind, правим, возвращаем в svn и т.д.

Как вариант можно создать в svn структуру, близко-аналогичную конечному документу, но тогда все прелести подхода единого источника уходят.... :(

Хочется как-то удобнее. :)

Одновременно с планированием структуры возникло еще несколько вопросов уже по самой dita:
- В описании dita for solo writers есть описание карты как таковой, а в XMLMind есть map (документ) и bookmap (книга)? В чем различие? На оазисе в описании 1.2 я не нашел такого деления.
- Правильно ли я понимаю, что карта может ссылаться (включать в себя) другие карты? http://docs.oasis-open.org/dita/v1.2/os ... f-metadata
Точнее не так. :) Правильный вопрос такой: могу ли я создать, например, карту "Все документы компании" для компиляции в xhtml и включить в неё карты "Руководства" (с вложенными картами для создания pdf "Бухгалтерия", "Закупка") и карты "Функционал" (с вложенными картами для создания pdf "Обработка документов", "Другая ерунда").
Такой подход будет корректен? :)
- В чем принципиальная разница использования разных типов топиков? Почему нельзя всегда использовать, например, concept-топики?
Я вижу разницу только в возможности применении разных стилей оформления. Если этим (разным оформлением) с точки зрения бизнес-потребности можно пренебречь, то можно использовать только concept-топики? Чувствую что я вроде не прав, но не могу понять где... :)

Уф. Владимир, надеюсь, на подсказки. :) Спасибо.
 
Цитата
Я пока вижу один вариант, котрый мне очень не нравится (потому что придется бегать два раза между двумя инструментами)
Какими? Редактор и SVN? Ну это нормально.
Цитата
3. Возвращаемся в svn и забираем файл на редактирование
Не понял, это как? Просто открываем файл и правим в редакторе.
Цитата
Как вариант можно создать в svn структуру, близко-аналогичную конечному документу, но тогда все прелести подхода единого источника уходят....
Это как удобно вам. Прелести единого источника никак не зависят от структуры хранения файлов. Все построено на ссылках ведь, никакого копирования и дублирования.
 
Цитата
XMLMind есть map (документ) и bookmap (книга)? В чем различие? На оазисе в описании 1.2 я не нашел такого деления.
- Правильно ли я понимаю, что карта может ссылаться (включать в себя) другие карты?
Точнее не так. :) Правильный вопрос такой: могу ли я создать, например, карту "Все документы компании" для компиляции в xhtml и включить в неё карты "Руководства" (с вложенными картами для создания pdf "Бухгалтерия", "Закупка") и карты "Функционал" (с вложенными картами для создания pdf "Обработка документов", "Другая ерунда").
Такой подход будет корректен? :)
Да
Bookmap заточен под публикацию печатных документов. PDF, DOC, RTF, которые предполагается распечатывать в виде книг. Т.е. там есть деления на Части, Главы, Разделы, Параграфы и т.п.
 
Цитата
Правильный вопрос такой: могу ли я создать, например, карту "Все документы компании" для компиляции в xhtml и включить в неё карты "Руководства" (с вложенными картами для создания pdf "Бухгалтерия", "Закупка") и карты "Функционал" (с вложенными картами для создания pdf "Обработка документов", "Другая ерунда").
Такой подход будет корректен? :)
Да. Так вообще и надо делать. Все что лишнее, отфильтруется и не попадет в документацию.
 
Цитата
В чем принципиальная разница использования разных типов топиков? Почему нельзя всегда использовать, например, concept-топики?
Принципиальная - в тегах. В каждом типе топика заложен свой набор тегов (в теории). Можно сказать, для большей дисциплинированности в разработке документации.

Task --  для описания шагов выполнения какого-то алгоритма. Удобен для пошаговых инструкций: Шаг 1, действие, команда, результат команды, результат действия; Шаг 2, подшаг 2.1 результат, подшаг 2.2 результат, и т.п. Нумерация шагов, подшагов.

Concept - обычное повествование.. Описание тех или иных функций,в нем сосредоточены всем привычные теги из HTML (p, ul, ol, fig и т.п.).

И так далее.
 
Цитата
Я вижу разницу только в возможности применении разных стилей оформления. Если этим (разным оформлением) с точки зрения бизнес-потребности можно пренебречь, то можно использовать только concept-топики? Чувствую что я вроде не прав, но не могу понять где... :)

Уф. Владимир, надеюсь, на подсказки. :) Спасибо.
Все верно - правы! Я так и делаю  :mrgreen:
Проще использовать topic-topic или topic-concept для описания пошаговых инструкций, глоссариев, обычных описаний и т.п., чем настраивать множество возможных тегов для одного и того же результата. Когда тегов будет не хватать, можно задействовать другой тип топика в документировании, но это вряд ли случится.

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

DocBook сильно отстал.
 
Добрый день.
Теперь мыс a7alex  дошли до  планирования структуры документации для единого источника,как структуры именно пакета документов,так и структуры внутри документа.Очень кардинально расходимся во мнениях.
Ссылки на госты - рассмотрели ,не подходит данная структуризация.
Может кто-то поделится полезными ссылками? Или (что вообще было бы восхитительно) собственным опытом?
 
Цитата
понятно, что ничего не понятно
Нашел описание на русском www.teamlead.ru/pages/viewpage.action?pageId=67240001
 
Цитата
a7alex пишет:
Посоветуйте, пожалуйста, систему
Help&Manual, http://www.helpandmanual.com/order.html
Для Ваших задач хватит и Professional-версии, 18700 рублей.
Изменено: 'H&M User' - 30.05.2013 18:42:18
Страницы: 1
Читают тему