Назад | Перейти на главную страницу

Как предоставить документацию для ИТ-инструментов?

Я хочу предоставить ИТ-инструмент для использования в Windows. Речь идет об фильтре ISAPI, и я хочу описать установку, работу и настройку.

В настоящее время это делается в текстовом файле, который является довольно полным, но я думаю, что он не очень удобен. Я думаю, что хорошо разбираюсь в какие должно быть в документации. Я хотел бы внести свой вклад в Как часть. Как лучше всего предоставить документацию администраторам веб-сервера Windows?

.CHM? .PDF? .DOCX? .HTM?

РЕДАКТИРОВАТЬ: Я было текстовый файл, но он становился очень длинным, и в нем были ограниченные возможности для связывания, перекрестных ссылок, индексации и организации. Понимаете, основной раздел подчеркивается знаками равенства, подраздел подчеркивается дефисом ... и т.д. и т.д. Я попытался отформатировать его таким образом, но в итоге файл .txt просто не масштабировался.


Обновить: Я выбрал ШФБ. Вот вывод HTML-справки. Что вы думаете? можно использовать?

Вот мой вывод:

  • Текст ASCII великолепен - я могу прочитать его где угодно
  • HTML на втором месте - я тоже могу читать это где угодно
  • PDF приемлем, но несколько раздражает, так как мне может потребоваться обратиться к нему на сервере без установленного PDF-ридера
  • CHM - это боль из-за глупого управления справкой HTML (спасибо, что справка HTML контролирует ошибки / уязвимости!), И это не очень удобный формат для вырезания / вставки из
  • DOCX просто раздражает - у меня на серверах не установлен "Office", и если мне нужно обратиться к документации там, я не буду загружать его

Вы должны проверить asciidoc. Я сделал с ним несколько коротких вещей, и результат получился довольно четким (и, конечно, настраиваемым). Простой текст по дизайну очень удобен для чтения, и вы можете легко получить документ, HTML и PDF. Используя любое количество других конвертеров, вы также можете преобразовать его в другие форматы, такие как CHM.

Однако очень универсальный пакет, поскольку он ориентирован на UNIX, я не знаю, как поддерживает Windows.

Мне нужно использовать правильно отформатированные текстовые файлы ASCII. Их можно читать с ноутбука, сервера, windows, unix, linux и т. Д.

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

На самом деле ... в крайнем случае ... Я даже мог бы прочитать текстовый файл со своего мобильного телефона, если бы мне пришлось.

Я уверен, что любой, кто застрял в коло-центре в 3 часа ночи при менее чем желательных обстоятельствах (например, пейджинг из бара, отсутствие ноутбука и т. Д.), Согласится. ;-)

Только мои 2 цента ...

reStructuredText мне подходит. Его легко изучить и использовать.

Я знаю, что вы уже приняли ответ, но я подумал, что рекомендую сфинкс. Вы пишете документ в reStructuredText, но можете легко сгенерировать html, доступный для поиска (крошечный javascript). /

Вот еще одно голосование за простой текст. Если документация требует или использует иллюстрации какого-либо типа HTML, это может быть лучшим выбором, потому что браузер, скорее всего, будет доступен, чем другие приложения для чтения.

Пожалуйста, никогда не используйте DOCX или любой другой проприетарный формат, если нет веской причины для этого (и я не могу придумать ни одного). Даже если вы хотите создать его как файл Word, сохраните его как DOC, а не DOCX, поскольку существует более широкий спектр программного обеспечения, которое может читать старый формат.