Разное

Здравствуйте. В каком формате лучше хранить документацию к CMS?

А4

pdf, txt

+1 к pdf

odf

Онлайн + оффлайновая версия в *.chm с полнотекстовым поиском.

Plain text - txt

> +1 к pdf
-1 :)

Пока использую формат doc, поскольку:

Достоинства

1. doc'и легко создавать и править.
2. doc'и легко могут быть изменены пользователями системы, если они добавляют новые функции.
3. Малый размер.
4. Содержимое doc'ов воспринимается поисковиками.
5. Поддержка изображений.

Как найти замену doc'ам? Какие форматы я пробовал:

html

+ Файлы меньше по размеру.
+ Документация online.

- (большой) - замучаешься верстать.

rtf

- (большой) - громадный размер файла 6-7 мегабайт

pdf

- файлы больше весят
- документация не поддается редактированию

- не у всех установленны офисные программы :)

TXT можно почитать где угодно :)

Да, мне любой формат, где были бы заголовки, списки, текст и картинки :) При этом без заморочек с версткой (html).

Есть еще альтернатива .abw - внутренний формат редактора AbiWord. Весят на 30% меньше doc. Но тогда пользователей придется просить скачать AbiWord (5.5mb)

-1 doc:
Лично я практически не пользуюсь офисными редакторами, я вспоминаю о них лишь тогда когда маман надо напечатать какой нить документ.
+1 html:
В ручную верстать не заставляют можно по шаблону делать или примитивная CMS в помощь

-+0 rtf:
кажется doc есть практически то же самое что и rtf

-+0 pdf
документацию ни кто не должет править под себя...

А так смотря какая CMS.
Если там черт ногу сломит, то нужно делать онлайн документацию однозначно(будут предложения по ее изменению, добавлению, исправлению) и дублировать txt файлом в архиве с линком на онлайн документацию.
Если же она понятна и так, то можно кратко в txt формате раписать все возможности и нужности

>>Лично я практически не пользуюсь офисными редакторами, я вспоминаю о них лишь тогда когда маман надо напечатать какой нить документ.

Забыл занести в минус, но с доками удобно работать автору документации и пользователи могут легко его поменять под свои нужды.

>>В ручную верстать не заставляют можно по шаблону делать или примитивная CMS в помощь

Можно даже блочный редактор CMS задействовать. А потом сгенеренный код вставить в шаблон. Только при работе с документацией мне хотелось бы иметь дело с документацией и никакого кода.

>> txt

С удовольствием! Только как я туда картинки вставлю! И еще выделение цветом, а такие элементарные вещи как жирный, курсив? :) Заголовки, списки делать научился. Кстати readme с инструкциями по инсталляции, деинсталляции, описанием сохраняются в txt.

>>дублировать txt файлом в архиве с линком на онлайн документацию

CMS делаю я один. Справляюсь. Только лишних забот с дублированием мне не надо :)

Идея такая: мне удобно составлять документацию, а пользователям удобно ей пользоваться. Пока лучше AbiWord ничего придумать не могу.

Так добавьте в свою CMS импорт в несколько форматов - doc, pdf и выдачу в txt.
Сами же ведите документацию отдельной темой на своей же CMS.
А каждый будет брать ее в удобном для себя формате.

Самая большая морока - сделать один раз скрипт импорта в разные форматы. Но в будущем это Вас освободит от конвертирования большого количества документов и от холиваров пользователей относительно форматов. Кто не захочет скачивать - может просто на вашем сайте почитать документацию. Есть же и такие люди. =)

З.Ы.: лично я предпочитаю pdf по причине невозможности его редактировать.

А можно уточнить про какую документацию идёт речь? Пользовательскую или для разработчиков. Для разработчиков можно её сгенерировать "на лету" если комментировать свой код согласно формату того же PHPdoc'a.

>>А можно уточнить про какую документацию идёт речь?

http://ortus.nirn.ru/index.php?ortupg=12

Я не имею ничего против формата pdf, однако мне не хотелось бы лишать пользователей возможности изменять доки. и Файлы на 25-30% больше доковских весят...

chm в локальное пользование + html на сайте

+1
chm

А как пользователю под *nix этот формат юзать?

-1 *, !odf
+1 odf

Есть ли удобный редактор chm, наподобие MS Word или AbiWord?

С abw - наврал. Файлы в 2 раза больше весят.

Обычно сам CHM не правят - это по сути набор HTML-страниц, скомпилированных таким образом, чтобы их можно было просматривать OffLine, впрочем OnLine-страницы тоже можно загружать.

PS Я обычно сохраняю документацию в базу данных, а потом подготоваливаю HTML-страницы, файл ключей и файл подразделов при помощи PHP-скрипта, затем компилирую полученные файлы в единое целое при помощи компилятора. В качестве компилятора лучше использовать не Microsoft-ский, а что-то более удобное, вроде htm2chm (по сути приложив немного усилий, актуальный CHM можно будет получать за пару кликов мышью).

Пока выбираю из двух вариантов

web-страница с фильтром + zip
pdf

cheops, можно вопрос? А в каком формате вы редактируете и сохраняете ваши книги? Я думаю мне бы он подошел :)

>А в каком формате вы редактируете и сохраняете ваши книги?
Word (требование издательства)

а кто вообще читает документацию?!?!

>>а кто вообще читает документацию?!?!

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

Другие руководства (дизайнера и программиста) тоже могут быть востребованы. Судя по вопросам на форуме.

wiki?

>>wiki

Ни разу не пользовался. Есть ли wiki-редактор наподобие word с поддержкой заголовков, списков, изображений, выделения цветом?

Там даже круче. Там немного специфический синтаксис, но зато позволяет писать не отрываясь от клавиатуры. Оформление заголовков, составление содержания, перекрестные ссылки и комментарии движок берет на себя. Многие считают что это, на сегодняшний день, идеальная среда для написания документации. Я готов с ними согласиться, хотя сам документацию в ней и не писал.