2

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?

seanm
  • 111
  • 1
  • 4
  • 1
    The doxygen manual itself is written by means of doxygen. The question is in what form do you have your input files for the user manual. – albert Dec 20 '21 at 15:52
  • Currently my input files are written in Markdown. I could pretty easily convert that to something else if needed since each content page is like 95% plain text with just a handful of Markdown tags (usually a link to an image, video, etc.) – seanm Dec 20 '21 at 16:49
  • I should have added that I was just starting the process of looking at using Doxygen right before my initial post, so the answer might be in there somewhere, but so far I haven't stumbled across any sort of how-to document/example that says "if you want to make a user's manual using Doxygen, here's how you do it...". The examples I can find are all related to documenting source code. – seanm Dec 20 '21 at 17:06
  • Doxygen can handle reasonably well standard markdown files. You should just try it with just giving as your inputs your markdown files to doxygen. See what you like / don't like. As you have some experience with doxygen creating a doxygen settings file shouldn't be a big issues. Btw. which version of doxygen are you using? – albert Dec 20 '21 at 17:25
  • I definitely plan to give Doxygen a shot (I've got 1.9.1 currently, but can upgrade to 1.9.2). I think I need to restructure my existing markdown files around a little before I can attempt that, but I do want to see if it's a reasonable option – seanm Dec 20 '21 at 19:20

1 Answers1

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.

Luis Iñesta
  • 401
  • 3
  • 6
  • This looks like it might be promising! I don't know a ton about Maven, but I can start to learn. My only concern is adding the Java and Maven dependencies (and whatever learning curve that comes with them). We're a small team (only 3 people) trying to both maintain the application itself as well as keep the documentation in sync with changes we make. So we want to keep this part of the process as simple as possible – seanm Dec 20 '21 at 16:55