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

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1
Ответить
RSS
Как организовать работу отдела документирования?
 
Товарищи начальники отдела документирования! Помогите советами. С чего начать и как настроить работу отдела документирования с "нуля". У нас открывается такой отдел. Пока есть два работника. Планируем принять 15. Соответственно, нужно все! И " единый источник" в котором будет разрабатываться документация,  варианты отчетности, и вообще как это все работает)?
 
а сколько человек у вас будет работать?
Работаю по-старинке...
 
А начальника уже нашли ?
 
Начальником буду я..возможно.. Пока у нас только два человека кроме меня, планируем брать третьего.
 
Советую выбрать для начала ПОР для разработки, написать всем инструкции, в том числе и для себя. Чтобы понимать кто и чем будет заниматься, ну а дальше контролируйте процесс.
Работаю по-старинке...
 
Потом зафиксировать требования к документированию: закрепить стили, утвердить терминологию, добавить корп.стандарты и т.п. чтобы результаты работы каждого сотрудника были частью общего дела, а не каждый сам по себе
 
Спасибо. Сейчас перерабатываем корпоративные стандарты. Написал план отдела на год. Понемногу растем. Документации нужно писать много. Столкнулся с проблемой сохранения версий документации. Это оказался очень тонкий момент. Кто-нибудь может посоветовать по тому как следить и хранить версионность документации?
 
а в чем она хранится?
 
просто в папках
Название документа> Номер версии>Документ Word и PDF
 
Цитата
просто в папках
Это не есть гуд. Хорошо бы воспользоваться какой-нить системой контроля версий. Если с этим сложности, то версионность можно отслеживать путем добавления индекса в название файла. Например, <название файла>_001.doc. До 100 идет работа над документом, согласование, утверждение, внесение изменений по результатам проверок. После внесения изменений индекс увеличивается на единицу. Индекс 100 означает, что документ готов и его можно передавать клиентам. При таком подходе в самом документе необходимо прописывать историю: версия 015 — внесены изменения по резултатам проверки тестеровщиками; в раздел 5.2.8 добавлена информация о подключении переферийных устройств; раздел 4.5.11 удален, информация из него перенесена в 8.12.13. Ну и т. п.
 
Цитата
При таком подходе в самом документе необходимо прописывать историю: версия 015 — внесены изменения по резултатам проверки тестеровщиками; в раздел 5.2.8 добавлена информация о подключении переферийных устройств; раздел 4.5.11 удален, информация из него перенесена в 8.12.13. Ну и т. п.
А если документ в PDF, то так просто не получится.

С файлами DOC проще - Microsoft Office SharePoint. Файлы загружаются на сервер, откуда доступ регулируется правами. Позволяет хранить историю изменений для каждого файла (только ее надо ручками прописывать или хранить в режиме исправлений). Позволяет блокировать файл в то время, как он редактируется другим пользователем. Посмотрите, там много разных возможностей, правда стоит такое ПО недешево.
 
Цитата
Это не есть гуд.
Это я и сам понимаю. За  вариант сортировки спасибо, удобно.

Что касается использования SharePoint, то это не для нашей компании точно) слишком дорого.
 
Цитата
А если документ в PDF, то так просто не получится.
Не вижу связи с форматом. Просвятите? ) Не удобно и дико для 21-го то века, но что делать, иногда и так извращаться приходится.
Цитата
Это я и сам понимаю. За вариант сортировки спасибо, удобно.
На самом деле удобного нет ничего. Слишком много человеческого фактора. Забыл индекс перещелкнуть и сиди потом в CompareIt сравнивай, вычищай. А если кто другой такой фигней пострадает? И концов уже не найдешь. Но на безрыбье, какгрица...

Цитата
Что касается использования SharePoint, то это не для нашей компании точно) слишком дорого.
За шарепоинт не скажу, не работал. 6-7 лет использовал в качестве системы контроля версий StarTeam. Удобная штука. Посмотрите, может, по деньгам она вам подойдет.
 
Цитата
Не вижу связи с форматом.
Расскажите как можно хранить изменения в файле PDF от версии к версии? Этот момент не встречали никогда.
 
Цитата
Расскажите как можно хранить изменения в файле PDF от версии к версии? Этот момент не встречали никогда.
Простите, я не понимаю о чем вы говорите. Есть документ, он "живет" на файлсервере. Надо каким-то образом отслеживать его версионность. При использовании системы контроля версии новая "ревизия" документа присваивается файлу автоматически. В любой момент времени доступна как старая версия файла, так и новая. Если пользователь не поленился и прописал в комментариях к новой ревизии документа отличия от старой, то совсем все хорошо...
У puhata, как я понял, сходные потребности, но работают они с файлсервером. Для того чтобы хоть как-то смоделировать в данном случае систему контроля версий, я предложил индексы в названии файла. Чтобы знать, чем файл с индексом 002 отличается от файла с индексом 003, необходимо вести внутри файла табличку с описанием изменений (или отдельный файл, как угодно). Причем тут расширение файла?
 
Цитата
Причем тут расширение файла?
Текстовые файлы свободно обрабатываются любыми системами контроля версий. Файл загружается на сервер, в его каталоге создаются системные файлы с хранением истории изменений. В любой момент времени можно посмотреть кто и что изменял путем сравнения двух ревизий файла без каких либо коментариев (см. SVN, Mercurial и т.п.)
Бинарные файлы (pdf, doc, jpg, gif, zip, exe и другие варианты, не обязательно документации) так обрабатываться не могут, т.к. нет программ для сравнения, за некоторыми исключениями.

Цитата
Простите, я не понимаю о чем вы говорите. Есть документ, он "живет" на файлсервере. Надо каким-то образом отслеживать его версионность.
Я говорю о том, что с бинарными файлами работать сложнее. Надо либо писать изменения вручную, о чем можно забыть или "забить", либо хранить их в системе контроля версий просто с индексами. В индексах также описывать изменения вручную, на что также можно забить/забыть.
Грубо говоря, есть 10 файлов PDF + 1 readme.txt, в котором написано кто что когда изменял. Изменил документ, будь добр запиши что ты изменил, когда и зачем :D
 
Цитата
Надо либо писать изменения вручную, о чем можно забыть или "забить", либо хранить их в системе контроля версий просто с индексами. В индексах также описывать изменения вручную, на что также можно забить/забыть.
Грубо говоря, есть 10 файлов PDF + 1 readme.txt, в котором написано кто что когда изменял. Изменил документ, будь добр запиши что ты изменил, когда и зачем :D
Про косяк с человеческим фактором я же ж писал :) Все верно. Расскажете как от него избавиться? Буду премного благодарен.
 
"До 100 идет работа над документом, согласование, утверждение, внесение изменений по результатам проверок. После внесения изменений индекс увеличивается на единицу. Индекс 100 означает, что документ готов и его можно передавать клиентам".
Думаю, что такая система нумерации не очень удобна. Кроме номера версии в название файла документа можно добавлять еще и статус (см. ГОСТ 2.051). Статусы могут быть различными - как примите у себя в отделе, например, документ в работе (статус "Р"), документ проверен (статус "П") и т.д. Тогда не потребуется такого количества версий, да еще и подойдете напрямую к описанию жизненного цикла документа.
Что касается "косяка с человеческим фактором", то нужно разрабатывать регламент на процесс разработки документации.
 
Мы говорим на разных языках. Я вообще не понимаю как можно править PDF и сохранять его разные промежуточные версии. Наверное ПДФ делается из Ворда или каких-то других систем разработки документации?? Если в ворде, то можно изменения хранить в самом файле (в 2007 исправления и изменения) пока не будет завершено редактирование и не обязательно хранить 100 файлов с именами от 001 до 100 с разными стандартами.

Если из других систем, то можно хранить исходники Subversion, он бесплатен, но полезен только для ""не бинарных" файлов. Встроенные утилиты позволяют посматривать изменения ( с подсветкой разницы).

Если есть тестирование документации по файлу ПДФ, то не стоит его переименовывать каждый раз с новым именем. Изменять исходники, хранить их в Subversion, а ПДФ собирать после каждого изменения - всегда последняя версия. Subversion позволяет откатить назад любые изменения до любого момента, если последняя версия не удалась, то легко откатываемся назад. Почитайте в нете. Я его не рекламирую, просто работаю с текстовыми исходниками много лет, с вордом работал, но не делал множество копий с обновлениями.

Или если я все не так понял, расскажите, плз, о каких версиях вы говорите :) В качестве обмена опытом.
 
Коллеги, мы действительно говорим с вами на разных языках. Я предложил один из вариантов по предъявленным вводным. Причем сразу оговорился, что вариант кривой. Предлагайте свои, а не пытайтесь доказать мне, что я неправ :)
Цитата
Кроме номера версии в название файла документа можно добавлять еще и статус (см. ГОСТ 2.051). Статусы могут быть различными - как примите у себя в отделе, например, документ в работе (статус "Р"), документ проверен (статус "П") и т.д.
Статусы не вариант. Вам все равно придется использовать индексы, потому что в пределах статуса, допустим, "Р", может быть многамнога ревизий этого документа. Задача в том, чтобы была возможность "вытащить" или откатиться на любую понадобившуюся вам ревизию.
И не произносите при мне эту аббревиатуру, пожалуйста, мне от нее плохо )))
Цитата
Тогда не потребуется такого количества версий, да еще и подойдете напрямую к описанию жизненного цикла документа.
Что касается "косяка с человеческим фактором", то нужно разрабатывать регламент на процесс разработки документации.
Процесс разработки у меня описан. Это первое, что я делаю, устраиваясь в новую контору. Параллельно с этим разрабатываются шаблоны. Это минимум. Далее, если есть время и не сильно влом, разрабатываются глоссарии, "идеальные" составы и структуры документов, наполнение стандартных разделов.
Вот только все это никак не может невилировать человеческий фактор. Несколько сокращает его, но полностью не избавляет, ибо, описанный ADVANCED принцип "забыть и забить", остается незыблимым. И если вы считаете, что, описав регламент, вы обойдете его стороной, то приготовьтесь рано или поздно наткнуться на кучу какой-нить субстанции, которую вам придется разгребать.
Цитата
Мы говорим на разных языках. Я вообще не понимаю как можно править PDF и сохранять его разные промежуточные версии. Наверное ПДФ делается из Ворда или каких-то других систем разработки документации??
А я где-то говорил про то, что правится сам пдф? Для меня пдф по умолчанию — конечный формат. Естественно, разрабатывается документ сначала в текстовом редакторе, откуда конвертируется в пдф.
Цитата
Если в ворде, то можно изменения хранить в самом файле (в 2007 исправления и изменения) пока не будет завершено редактирование и не обязательно хранить 100 файлов с именами от 001 до 100 с разными стандартами.
Можно подробнее о том, как именно это реализуется в ворде? Можно работать с одним файлом под одним именем, при это каждая новая сессия работы с документом сохраняется отдельно в какой-то служебный файл, из которого потом можно вытащить любую версию? Это в ворде? Это не фантастика?
Цитата
Если из других систем, то можно хранить исходники Subversion, он бесплатен, но полезен только для ""не бинарных" файлов. Встроенные утилиты позволяют посматривать изменения ( с подсветкой разницы).
Ну так выше я говорил о StarTeam. Он платен, но для меня работать с ним было очень удобно. В нем нет встроенных утилит для подсветки изменений, но мне для этих целей всегда хватало CompareIt, который, кроме всего прочего, дает статистическую инфу об изменениях в процентах, что очень удобно для отчетности и подсчета производительности труда техписа.
Цитата
Если есть тестирование документации по файлу ПДФ, то не стоит его переименовывать каждый раз с новым именем. Изменять исходники, хранить их в Subversion, а ПДФ собирать после каждого изменения - всегда последняя версия. Subversion позволяет откатить назад любые изменения до любого момента, если последняя версия не удалась, то легко откатываемся назад. Почитайте в нете. Я его не рекламирую, просто работаю с текстовыми исходниками много лет, с вордом работал, но не делал множество копий с обновлениями.
Еще раз: пдф — конечный формат. Работа над документом ведется в ворде. Как только она завершается, документ конвертируется в пдф и выкладывается в соответствующую папку. Он там единственный, чтобы люди не в теме всегда брали актуальную версию, а не рыскали наугад по списку из 354 файлов.

Цитата
Или если я все не так понял, расскажите, плз, о каких версиях вы говорите :) В качестве обмена опытом.
Я говорю о том, как можно попытаться смоделировать на файлсервере принцип системы контроля версий — при помощи индексов в названии файла. Это криво, работать с этим неудобно, постоянно допускаются ошибки, природу которых, в ряде случаев, узнать будет очень на не просто. Но без RCS я других возможностей не вижу.
Если вы их знаете, расскажите, буду премного благодарен )
 
Начните с регламента описания технологического процесса. Вот неполный, но важный перечень процессов при создании документации.
 
Весь сыр-бор разгорелся из-за неправильного выбора ПО создания документации. Word не годится. К примеру, у нас используется Help&Manual, а он поддерживает контроль версий:
1) Visual SourceSafe Version Control (VSS);
2) Subver sion (SVN):
 - Tortoise SVN - рекомендуется;
 - Collabnet;
 - Visual SVN;
 - UberSVN.

Так как <%VERSION%=<%VERSION_MAJOR%>.<%VERSION_MINOR%>.<%VERSION_BUILD%>, то эти встроенные переменные проекта используем следующим образом:
19 ГОСТ:
Major Version=RU
Minor Version=АБВГ
Build Version=00001-01 32 01
34 ГОСТ:
Major Version=АБВГ.502120
Minor Version=001.И3
Build Version=01

Все проекты H&M лежат на файл-сервере в форматах hmxp в папках h&m-проектов. Сниппеты и подключаемые repository-проекты всех видов документов хранятся в отдельных папках шаблонов проектов и подключаются при необходимости (для формирования единого источника данных).

Выходные документы публикуются в заранее сформированные папки, например: \2013\АСИВТ\ЭТАП2\РД\ а имя файла задается при запуске publish-задачи, к примеру: "Программа и Методика АСИВТ v.2.1.pdf". При необходимости, меняем Build Version проекта, а сам проект в процессе работ сохраняем в базу SVN (Bind current project to Subversion).
Изменено: 'H&M User' - 13.06.2013 17:50:47
 
Цитата
'H&M User' пишет:
сохраняем в базу SVN
SVN, если я правильно помню, это система контроля версий?
 
Цитата
Ogre пишет:
SVN, если я правильно помню, это система контроля версий?
Да, Subver sion (http://ru.wikipedia.org/wiki/Subversion). Разработчики H&M рекомендуют использовать Tortoise SVN (как расширение проводника Windows) в качестве наиболее предпочтительного клиента Subversion. При работе с системами контроля версий, H&M автоматически обнаруживает все установленные в системе клиенты. Если какой-нибудь из клиентов Subverson установлен, то в меню Vesrsion Control доступны опции сохранения и подключения текущего проекта в репозиторий SVN и обратно (подключение к проекту SVN и конвертирование его в локальную копию H&M).
Изменено: 'H&M User' - 14.06.2013 11:15:13
 
Я не очень понимаю, как все сказанное стыкуется с этой цитатой.
Цитата
'H&M User' пишет:
Весь сыр-бор разгорелся из-за неправильного выбора ПО создания документации. Word не годится.
Страницы: 1
Ответить
Читают тему
Форма ответов
 
Текст сообщения*
Загрузить файл или картинкуПеретащить с помощью Drag'n'drop
Перетащите файлы
Ничего не найдено
Загрузить картинки
Отправить Отменить