Как доставить документацию по ИТ-инструментам?
Я хотел бы предоставить ИТ-инструмент для использования в Windows. Дело в том, что это ISAPI Filter, и я хочу описать установку, операции и настройку.
В настоящее время это делается в текстовом файле, который является довольно полным, но я думаю, что это не очень удобно. Я думаю, что у меня есть хорошее представление о том, что должно быть в документации. Я хотел бы получить информацию о части. Каков наилучший способ доставки документации для администраторов веб-сервера Windows?
.CHM?.PDF?.DOCX?.HTM?
РЕДАКТИРОВАТЬ: У меня был текстовый файл, но он становился очень длинным, и у него было ограниченное средство для ссылок, перекрестных ссылок, индексации и организации. Давайте посмотрим, основной раздел подчеркнут знаками равенства, подраздел подчеркнут штрихами... и т. Д. И т. Д. Поэтому я попытался отформатировать его таким образом, но в итоге файл.txt просто не масштабировался.
Обновление: я выбрал SHFB. Вот выходная справка HTML. Как вы думаете? годный к употреблению?
6 ответов
Вот мой дубль:
- ASCII текст отличный - я могу прочитать это где угодно
- HTML - второй по значимости - я тоже могу читать это где угодно
- PDF приемлем, но несколько раздражает, так как мне может понадобиться обратиться к нему на сервере без PDF-ридера
- CHM - боль из-за глупого HTML-элемента управления справкой (спасибо HTML-справке об ошибках / уязвимостях!), И это не очень удобный формат для вырезания / вставки из
- DOCX просто раздражает - у меня не установлен "Office" на моих серверах, и если мне нужно обратиться к документации там, я уверен, что не буду загружать его
Я знаю, что вы уже приняли ответ, но я подумал, что порекомендую сфинкса. Вы пишете документ в reStructuredText, но можете легко генерировать html с возможностью поиска (крошечный javascript). /
Вы должны проверить Asciidoc. Я сделал несколько коротких вещей с ним, и вывод его довольно острый (и настраиваемый, конечно). Простой текст очень удобен для чтения, и вы можете легко выводить документы, HTML и PDF. Используя любое количество других преобразователей, вы также можете преобразовать его в другие форматы, такие как CHM.
Очень универсальный пакет, будучи UNIX-ориентированным пакетом, я не знаю, как работает поддержка Windows.
Я должен идти с правильно отформатированными текстовыми файлами ASCII. Их можно прочитать с ноутбука, сервера, windows, unix, linux и т. Д.
Мне не нужно полагаться на веб-браузер, Adobe Reader, Office или любую другую программу, чтобы узнать, как установить что-то на моем сервере. Это должно быть просто и безболезненно.
Правда... в крайнем случае... Я мог бы даже прочитать текстовый файл с моего мобильного телефона, если бы мне пришлось.
Я уверен, что любой, кто застрял в заведении "Коло" в 3 часа ночи при менее чем желательных обстоятельствах (т. Е. Выгнали из бара, без ноутбука и т. Д.), Согласится.;-)
Просто мои 2 цента...
Вот еще один голос за простой текст. Если документация требует или пользуется преимуществами иллюстраций какого-либо HTML, это может быть лучшим выбором, потому что браузер более доступен, чем другие приложения для чтения.
Пожалуйста, никогда не используйте DOCX или любой другой проприетарный формат, если нет веских причин для этого (и я не могу придумать ни одного). Даже если вы хотите создать его в виде файла Word, сохраните его как DOC, а не DOCX, поскольку существует более широкий спектр программного обеспечения, способного считывать старый формат.
reStructuredText мне подходит. Это легко учиться и использовать.