Create a maintainable user manual for application

Question

I'm trying to create a nice looking, easy to maintain user manual for an internal (not public) software application.

At a high level, these are the requirements:

1. The documentation the user browses will be static HTML pages.
2. The documentation needs to be able to be browsed from the user's hard drive. The pages will not be served on a web server. Or stated another way, there will be a top level doc directory on the user's hard drive which contains the initial index.html and then a directory tree structure containing the rest of the content. The user can double click that index.html from their own hard drive to get started and most (if not all) of the other content (pages, images, videos, etc.) are also on the user's device.
3. The basic layout of the site needs to be just a left pane with the table of contents of the user manual, and then the right hand side contains the section content.
4. I'd prefer to have the raw content in something easy to maintain. I'm thinking Markdown, but I'm open to other suggestions if there is something better. Markdown seems really simple though, so it seems like a pretty good candidate for the raw content. The user manual developer(s) shouldn't need to know HTML or CSS to be able to add content.
   a. We run "something" to generate the HTML from the raw content into HTML with nice looking CSS applied to it.

I feel like something like this already exists out there, but I don't seem to be coming up with the right search keywords to find it.

Currently, I'm playing around with a static site generator and having somewhat mixed results. I haven't played around with many of them yet - I stumbled across Hugo ( https://gohugo.io/ ) and I've been playing around with that. As I've gone down the Hugo rabbit hole, I seem to be encountering a square peg/round hole issue at times. It seems mostly geared towards generating web blogs, which isn't my exact use case so I've struggled a bit with getting it to work from a user's device. It also seems to be very sensitive to how the raw content is laid out to clue it in as to how to build the output HTML tree structure. I'm sure part of that is just a learning curve issue on my end (I'm not a web developer at all, so all of that is new to me), but at times it feels like I'm spending more time trying to understand why/how Hugo is going to render the HTML than actually just creating the content.

I've also seen rumblings online (particularly User manual with Doxygen ) about using Doxygen to generate a user manual but I haven't found any good examples about how to actually pull that off. We're already using Doxygen to document our code, so that might be a nice solution since it's just one less tool dependency/learning curve for the developers to figure out.

Anyone have any solutions they've found to do something similar that they like?

Answer 1

Just a few days ago I published a documentation site generation tool: https://luiinge.github.io/docsite-maven-plugin

It's written in Java and aimed to Maven projects, but even if your project is built with any other technology, you always can make an empty Maven project, with a minimal pom.xml file focused on the documentation. In case you're interested I could provide you with further information.