Создать удобное в обслуживании руководство пользователя для приложения

Question

Я пытаюсь создать красивое, простое в обслуживании руководство пользователя для внутреннего (не общедоступного) программного приложения.

На высоком уровне это требования:

1. Документация, которую просматривает пользователь, будет представлять собой статические HTML-страницы.
2. Документацию необходимо просматривать с жесткого диска пользователя. Страницы не будут обслуживаться на веб-сервере. Или, другими словами, на жестком диске пользователя будет каталог документов верхнего уровня, который содержит начальный index.html, а затем древовидную структуру каталогов, содержащую остальную часть содержимого. Пользователь может дважды щелкнуть этот index.html на своем жестком диске, чтобы начать работу, и большая часть (если не весь) другого контента (страницы, изображения, видео и т. Д.) Также находится на устройстве пользователя.
3. Базовый макет сайта должен быть просто левой панелью с оглавлением руководства пользователя, а затем правая сторона должна содержать содержимое раздела.
4. Я бы предпочел, чтобы необработанный контент был чем-то простым в обслуживании. Я думаю о Markdown, но я открыт для других предложений, если есть что-то получше. Однако Markdown кажется действительно простым, поэтому он кажется довольно хорошим кандидатом для необработанного контента. Разработчику (разработчикам) руководства пользователя не нужно знать HTML или CSS, чтобы иметь возможность добавлять контент.
   а. Мы запускаем «что-то», чтобы сгенерировать HTML из необработанного содержимого в HTML с примененным к нему красивым CSS.

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

В настоящее время я играю с генератором статических сайтов и получаю несколько неоднозначные результаты. Я еще не играл со многими из них - я наткнулся на Хьюго (https://gohugo.io/), и я играл с этим. Когда я спустился в кроличью нору Хьюго, я, кажется, иногда сталкивался с проблемой квадратного колышка / круглого отверстия. Похоже, что он в основном ориентирован на создание веб-блогов, что не является моим точным вариантом использования, поэтому я немного боролся с тем, чтобы заставить его работать с пользовательского устройства. Также кажется, что он очень чувствителен к тому, как выкладывается необработанный контент, чтобы понять, как построить древовидную структуру выходного HTML. Я уверен, что отчасти это связано с моей кривой обучения (я вообще не веб-разработчик, так что все это ново для меня), но иногда мне кажется, что я трачу больше времени, пытаясь понять, почему и как Хьюго собирается рендерить HTML, чем на самом деле просто создаю контент.

Я также видел в Интернете грохот (особенно руководство пользователя с Doxygen) об использовании Doxygen для создания руководства пользователя, но я не нашел хороших примеров того, как на самом деле это осуществить. Мы уже используем Doxygen для документирования нашего кода, так что это может быть хорошим решением, поскольку разработчикам остается лишь на одну кривую зависимости от инструмента / обучения меньше.

У кого-нибудь есть какие-то решения, которые они нашли, чтобы сделать что-то подобное, что им нравится?

Answer 1

Всего несколько дней назад я опубликовал инструмент для создания сайта с документацией: https://luuiinge.github.io/docsite-maven-plugin .

Он написан на Java и предназначен для проектов Maven, но даже если ваш проект построен с использованием какой-либо другой технологии, вы всегда можете сделать пустой проект Maven с минимальными затратами ресурсов. pom.xmlфайл ориентирован на документацию. В случае, если вы заинтересованы, я мог бы предоставить вам дополнительную информацию.