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

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1
RSS
Опыт перехода на DITA, опыт перехода на Dita
 
Интересная статья из Интернета об опыте перехода на Dita

"Вот и настал тот момент, когда мы решили переходить на диту. Точнее, мы ничего не решали - за нас все решили. Появился новый менеджер, сделал красивую презентацию и убедил всех в том, что дита спасет мир. Я не спорю… технология сама по себе отличная. Вопрос в том, что перевести 4 огромных проекта на диту одновременно, в условиях нашей компании, невозможно. Точнее возможно, но понадобится нам на это лет так…5. Это только для того, что бы достигнуть того уровня документации на котором мы сейчас находимся, то есть, чтобы сделать что-то лучше нужно еще пару лет накинуть. И вопрос не в том, что дита плохая…нет. Просто переходить на нее надо с умом. История длится уже 3 месяца и до дедлайна у нас еще есть месяцев 8. На данный момент:
  • Мы потеряли ссылки между топиками
  • Мы потеряли видео в файлах
  • Мы больше не поддерживаем имиджмепы
  • Мы создали уже 20000 xml файлов, которые нужно будет как-то поддерживать, и это только описание интерфейса
  • Мы не поддерживаем свой css
  • Мы имеем целую кучу файлов, содержащих только таблички и процедуры, которые, вероятнее всего, никто никогда читать не будет
  • Мы потеряли контекстный вызов хелпа
  • И, лично я, имею целую кучу вопросов на которые мне никто не может ответить.
Для тех, кто стоит на пороге принятия решения о переходе на эту технологию, еще раз хочу заметить, что проблема не в самой дите, а в том каким образом мы на нее переходим. Пожалуй, могу перечислить несколько пунктов, которых неплохо было бы придерживаться при конвертации в диту:
  • Определитесь зачем вы это делаете и что вы выигрываете с этим переходом.
  • Не пытайтесь перевести все проекты одновременно.
  • Подумайте о том, что при переходе на диту 60% работы. должны выполнять программисты. Одним текрайтерам не справится.
  • Убедитесь, что в компании есть хотя бы один человек, который действительно знает, что такое дита.
  • Не пытайтесь создать что-то с нуля. Используйте, ту документацию, которая у вас уже есть.
  • Наймите побольше студентов для монотонной работы.
К сожалению, мы не соблюдали ни один из вышеперечисленных пунктов, и поэтому уже на самой начальной стадии у нас очень много проблем. Эта история только началась, но конца ей пока не видно.
 
Я считаю что краски несколько сгущены. В общем, рецепт по переходу на DITA достаточно прост.
1) Фактически основополагающее: Нужен человек который может  разобраться в среде на уровне программиста - т.е. подделать код плагинов тулкита под конкретные нужды. Для это го потребуется время, если разбираться с "нуля", то несколько месяцев. Но что мы имеем в итоге?
2) В итоге получается, что "пользователи" только наполняют контент, который выпускается и группируется практически любым образом. Перевести все в топики проблем особых нет - сиди и переводи (можно и студентов привлечь). Оформляй все по правилам и будет счастье - спец. редакторы не дадут сильно в сторону отступить.

О чем стоит подумать. Приемлемое оформления документов может добиться и тех. писатель, за пару месяцев разбираясь сам, или через пару недель, пользуясь подсказками.
Есть только большое "НО" - идея среды отличается от привычной большинству и по умолчанию не соответствует "условно ГОСТовскому оформлению". Программист может это исправить, но совсем все обойти, возможно, не получится - это цена независимого контента.
И главное, с чем пришлось столкнуться - начальство не до конца понимает идею построения документа из отдельных топиков. Приходится допиливать топики под конкретную задачу - что не совсем верно.
Если задуман переход на DITA, стоит подумать - можно ли вообще составить документацию из топиков, если виденья этого нет на всех уровнях, то получится что документы будут иметь другой формат. Выгоды от такой системы никакой - одни проблемы.
 
Цитата
aLeks пишет:
Если задуман переход на DITA, стоит подумать - можно ли вообще составить документацию из топиков, если виденья этого нет на всех уровнях, то получится что документы будут иметь другой формат. Выгоды от такой системы никакой - одни проблемы.
Вот этот момент интересен, как действительно понять нужна на предприятии документация из топиков или лучше с этим и не связываться?
 
Цитата
aLeks пишет:
О чем стоит подумать. Приемлемое оформления документов может добиться и тех. писатель, за пару месяцев разбираясь сам, или через пару недель, пользуясь подсказками.
Есть только большое "НО" - идея среды отличается от привычной большинству и по умолчанию не соответствует "условно ГОСТовскому оформлению". Программист может это исправить, но совсем все обойти, возможно, не получится - это цена независимого контента.
И главное, с чем пришлось столкнуться - начальство не до конца понимает идею построения документа из отдельных топиков. Приходится допиливать топики под конкретную задачу - что не совсем верно.
Если задуман переход на DITA, стоит подумать - можно ли вообще составить документацию из топиков, если виденья этого нет на всех уровнях, то получится что документы будут иметь другой формат. Выгоды от такой системы никакой - одни проблемы.
Я это вообще не понял.

Есть только большое "НО" - идея среды отличается от привычной большинству - это как понять ?


и по умолчанию не соответствует "условно ГОСТовскому оформлению" - а что соответствует?

Программист может это исправить, но совсем все обойти, возможно, не получится - это цена независимого контента.
Что именно обойти и что должно получиться и почему не получится? Нет ничего не возможного.

И главное, с чем пришлось столкнуться - начальство не до конца понимает идею построения документа из отдельных топиков. Приходится допиливать топики под конкретную задачу - что не совсем верно.

Видимо вы не так показали начальству идеи построения документов. Идей много и все они не сложные. Что значит допиливать топики под конкретную задачу ?
 
Есть куча плагинов, которые конвертируют вашу документацию в dita-формат и обратно.
Конечно из PDF напрямую в XML врядли, но вы же сами и не редактируете PDF. Любой редактируемый формат можно конвертнуть в любой другой формат. А работать с XML очень просто.

Среды, в которых используется собственная БД (h&m, например) сложнее конвертнуть во что-либо, но тоже можно.  
 
Соглашусь, если у вас сотни документов ежедневно изменяются и отправляются заказчикам, то переводить все это в DITA нет смысла. Но, можно начать "с понедельника" создавать топики для определенных документов, которые не зависят от прежних инструментов. Старая документация со временем перейдет в архив, новая постепенно будет разрабатываться в XML.

Стили все настраиваются как угодно, по ГОСТ или не ГОСТ. Можно настроить так, что никто не найдет разницы. В то же время при  использовании DITA не нужно заморачиваться стилями ("поплыло/не поплыло" ;)  каждый раз при сохранении документа.
 
Цитата
'""""ADVANCED""""' пишет:
Я это вообще не понял.

Самая первая идея DITA это повторное использование контента, и это, отвечая на вопрос  ''writer'', значит, что единожды написанный топик используется в "множестве" документов. Тут начинаются проблемы:

Есть только большое "НО" - идея среды отличается от привычной большинству - это как понять ?

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

и по умолчанию не соответствует "условно ГОСТовскому оформлению" - а что соответствует?

Нумирацию и ссылки с номерами разделов. Мой вопрос об этом в соседней теме, кстати, остался без ответа... Причем не только здесь, но и на http://tech.dir.groups.yahoo.com/group/dita-users/

Цитата
Программист может это исправить, но совсем все обойти, возможно, не получится - это цена независимого контента.
Что именно обойти и что должно получиться и почему не получится? Нет ничего не возможного.

Можно написать свою DIT'у с ... тем чем надо.
Проблемы те же, что и выше: разные размеры страниц, ссылки с нумерацией, формирование разделов документа, которые должны присутствовать/отсутствовать в оглавлении (Формат bookmap с его частями и главами не подходит)

Цитата
И главное, с чем пришлось столкнуться - начальство не до конца понимает идею построения документа из отдельных топиков. Приходится допиливать топики под конкретную задачу - что не совсем верно.

Видимо вы не так показали начальству идеи построения документов. Идей много и все они не сложные. Что значит допиливать топики под конкретную задачу ?

Идея единого источника идет от начальства, которое не до конца понимает этот принцип. Тут, опять же, главное ссылки внутри документа (потому что нужно и раньше везде было), слишком обезличенные топики и пр. на том же уровне.
 
Цитата
'""""ADVANCED""""' пишет:
Есть куча плагинов, которые конвертируют вашу документацию в dita-формат и обратно.
Конечно из PDF напрямую в XML врядли, но вы же сами и не редактируете PDF. Любой редактируемый формат можно конвертнуть в любой другой формат. А работать с XML очень просто.

Среды, в которых используется собственная БД (h&m, например) сложнее конвертнуть во что-либо, но тоже можно.
Та же самая dita4publishers конвертирует весьма криво. Настолько, что проще "скопипастить", причем топики не должны быть объемные...
Это выражается в том, что получаемые топики - "концепт", и все содержание в одну строку, что-то править там замучаешься.
Страницы: 1
Читают тему