В чем оформлять документацию? Опции

[ataradov]

У многих крупных фирм, где выпускается множество документации, эта самая документация оформлена в едином стиле. Так вот может знает кто, что именно они используют?

И что можно порекомендовать использовать для это цели? ТеХ это конечно здорово, но проблемы с таблицами и необходимость все долго затачивать убавляют оптимизм. Желательно что-нибудь работающее из коробки и с простым синтаксисом типа как в wiki.

[dissector]

У многих крупных фирм, где выпускается множество документации, эта самая документация оформлена в едином стиле. Так вот может знает кто, что именно они используют?

И что можно порекомендовать использовать для это цели? ТеХ это конечно здорово, но проблемы с таблицами и необходимость все долго затачивать убавляют оптимизм. Желательно что-нибудь работающее из коробки и с простым синтаксисом типа как в wiki.

См. здесь. Но насчет простого синтаксиса в вики у меня нет такого оптимизма. Единый стиль - посадите выпускающую девочку, пусть после версии для печати из вики штампы в документы ворда вставляет И будет единый стиль...

[bve]

У многих крупных фирм, где выпускается множество документации, эта самая документация оформлена в едином стиле. Так вот может знает кто, что именно они используют?

И что можно порекомендовать использовать для это цели? ТеХ это конечно здорово, но проблемы с таблицами и необходимость все долго затачивать убавляют оптимизм. Желательно что-нибудь работающее из коробки и с простым синтаксисом типа как в wiki.

Документация документации - рознь!
Если выпускаете конструкторскую - чертежи, схемы, спецификации и т.п. - неплох Компас,
у него же есть подсистема ведения архива ( подлинники, извещения, измененные, удаленные и пр. )
Если другое - тут что кому удобнее...

[sio83]

Документация документации - рознь!
Если выпускаете конструкторскую - чертежи, схемы, спецификации и т.п. - неплох Компас,
у него же есть подсистема ведения архива ( подлинники, извещения, измененные, удаленные и пр. )
Если другое - тут что кому удобнее...

Причем единого стандарта может не быть. У меня на работе ИИ оформляют кому в чем нравится - кто в P-Cadе, кто в AutoCadе (причем оба случая имеется в виду не на схемы с чертежами, где это логично из соображений копипейста, а на текстовые документы), кто в ворде... А после того, как я увидел нарисованный в P-Cadе паспорт, я уже ничему не удивляюсь...

[dissector]

А после того, как я увидел нарисованный в P-Cadе паспорт, я уже ничему не удивляюсь...

Мир полон альтернативно одаренными людьми Кто-то в ёкселе умудряется чертить эскизы мебели и пишет в нем же большие статьи, кто-то макромедийным Firework'сом рисует трехмерную графику...

[unit900]

Хахаха.... Очень забавно!!!

Мы у себя в конторе, (немецкая занимается выпуском ASIC) используем Open (прости Гоосподи) Office. Да и то только потому что бесплатная, а это согласитесь сейчас начинает приобретать актуальность.
Это конечно не фонтан, но не плохая альтернатива MS Office.

[dissector]

Это все не то. Офис принципиально не предназначен для разработки документации. Максимум, на что он пригоден - писать в нем служебные записки и прочие кляузы.

Для профессиональной разработки документации, особенно в громадных объемах, потребуется соответствующий инструментарий single source. Без единого исходника делать нечего, если надо подготовить комплект из десятков документов объемом в несколько тысяч страниц.

В ТАНТК им. Бериева народ юзает FrameMaker - долго и успешно. У них объемы - десятки и сотни тысяч страниц. Типа "Руководств по лётной эксплуатации" и т.д. Сам пользуюсь AuthorIT'ом - этот инструмент вполне подходит для моих объемов. От фрейма отличается большей "визивиговостью".

Что касается wiki - штука интересная. Более того - приходится в ней и работать, поскольку команда разработчиков в 70 человек в нее все отписывает. НО! Вики не терпит больших объемов. ТЗ на двести страниц в ней не сделать - обругается. Приходится хранить в вики оперативную информацию и интегрировать вики с AuthorIT'ом. Тогда все более-менее нормально выходит.

Про бесплатный инструментарий не скажу - не знаю толком ничего о нем.

[Doka]

У многих крупных фирм, где выпускается множество документации, эта самая документация оформлена в едином стиле. Так вот может знает кто, что именно они используют? И что можно порекомендовать использовать для это цели? ТеХ это конечно здорово...

используется принцип разделения содержания текста от того как он будет представлен (аналог таблицы стилей (CCS) для HTML).
В мире технической документации для этого используются специальные стандарты. Мне наиболее продвинутым и прогрессивным показался DocBook.
а ТеХ это совсем не здорово, а вчерашний день. Если сегодня начинать работать с написанием тех.документации, то разумнее остановить свой выбор на _стандарте_ , основанном на XML, как наиболее универсальном и продвинутом языке структурированной разметки текстов.

И что можно порекомендовать использовать для это цели? ТеХ это конечно здорово, но проблемы с таблицами и необходимость все долго затачивать убавляют оптимизм. Желательно что-нибудь работающее из коробки и с простым синтаксисом типа как в wiki.

если с простым синтаксисом как в Вики - то и возъмите, например, MoinMoin Wiki Engine - там присутствует возможность хранения текстов в формате того же DocBook.


ссылки для lazyusers:
* WikiPedia o MoinMoin
* WikiPedia o DocBook

[dissector]

Doka, привет коллегам с РТФ от ЭТФ

[Kostos]

Хахаха.... Очень забавно!!!

Мы у себя в конторе, (немецкая занимается выпуском ASIC) используем Open (прости Гоосподи) Office. Да и то только потому что бесплатная, а это согласитесь сейчас начинает приобретать актуальность.
Это конечно не фонтан, но не плохая альтернатива MS Office.

А посему "(Прости Господи)"? Если все работает?

ЗЫ я не об религии, об принципе

[CodeWarrior1241]

Я в последнее время полюбил Doxygen - http://www.stack.nl/~dimitri/doxygen/ - для оформления тех. документации, для тех случаев когда надо писАть про firmware, код, и тому подобное. К этому пользуюсь graphviz для рисунков bubble diagrams, flows, memory maps, итд. Естесвенно такая прелесть можит работать только под Линукс. Изюминка связки doxygen + graphviz является то что как и все под линуксом, инфо сохроняется в config files, соответственно можно эти конфиги содержать вместе с кодом в repository - т.е. в CVS, subversion, или (не дай бог) в ClearCase (чтоб они все подохли нездорово себя чуствовали). Получается что можно легко создать make file которая автоматически реагирует на изменения в source коде каждый раз когда происходит изменение.

Теперь я вставляю в doxygen config file сам текст документации, и заставляю doxygen выдавать все в том формате которым пользуется фирма - т.е. headings параграфов, энумерация, итд. можно сохранить так как сотрудники предпочитают видеть. В dox config можно вставить и требованье вставить в документ соответствущие .png and .jpeg диаграммы которые создаются автоматически из grapfviz config files. Все это дело превращяется в .rtf файл который, по идее, не нуждается в ручной поправке в Word или OpenOffice.

[Doka]

Изюминка связки doxygen + graphviz является то что как и все под линуксом, инфо сохроняется в config files, соответственно можно эти конфиги содержать вместе с кодом в repository - т.е. в CVS, subversion.. Получается что можно легко создать make file которая автоматически реагирует на изменения в source коде каждый раз когда происходит изменение.

да-да!! это наш путь!!!
наполнение отдельно от оформления + поскольку всё в текстовом виде, то доступны все прелести систем контроля ревизий..
..что-то я опять про DocBook

[Andrew2000]

... Естесвенно такая прелесть можит работать только под Линукс.

Ну, эт вы загнули. Давно и успешно пользую сию связку и в форточках.

А вот такую штуку http://drawtiming.sourceforge.net/ хотел бы в виндах поиметь (у меня не собралось, а разбираться времени пока нет) - может есть у кого?

[CodeWarrior1241]

Странно. У меня grapfhviz не хотел нормально работать под виндой. Хотя, если честно, я особенно не пер в ту сторону, мы давно под линукс пересели.