Создание файла справки в формате HTML

Question

Передо мной стоит увлекательная задача по созданию файла справки для большого проекта.Я отказался от CHM-файлов из-за ограничений и теперь просматриваю файлы на основе HTML, но я все еще не определился с форматом....

Есть 3 области, на которых я сосредотачиваюсь:

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

Функциональность поиска Я хотел бы иметь возможность искать свободный текст в файле.

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

Сначала я склонялся к вики-подходу, использующему плагины для экспорта вики в статические страницы для распространения, но я не нашел такого решения...

Есть какие-нибудь предложения от вас, ребята, по этому поводу?Делаю ли я файлы справки слишком сложными?

Заранее спасибо!

Answer 1

Возможность повторного использования

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

В качестве альтернативы вы можете создать сниппет или фрагмент HTML с информацией для этого раздела, а затем использовать Server-Side Includes (или аналогичную технологию), чтобы включить его встроенным везде, где это необходимо.Таким образом, будет казаться, что контент был написан на каждой отдельной странице, но когда вам нужно внести правку, он по-прежнему находится только в одном месте.

Поиск

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

Пригодность для печати

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

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

Конечно, мы можем предложить всевозможные идеи о том, как достичь любой из этих целей, но поскольку звучит так, будто в данный момент вам нужен общий совет, это мой.

Answer 2

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

Я использую ДокуВики который поддерживает экспорт страниц.Вы можете поместить всю вашу вики-страницу в обычный текст, XHTML или XHTML body (для размещения внутри вашего собственного шаблона или для добавления в один файл для печати и т.д.).

Надеюсь, это поможет!