3

Are there any software packages out there for generating a nice looking users manual for small projects? I'm not talking about source documentation. I want to create an end users manual that doesn't look like I spent 20 mins in Microsoft Word.

hfitzwater
  • 171
  • 4
  • 1
    Presentation is important - but content is king. It doesn't matter what tool you use, if you only spend 20 minutes writing the manual, it'll be crap. In your situation, I'd spend my time in a tool designed for writing - MS Word - and put my effort into the content. Presentation and cross references come second. – Bevan Sep 30 '11 at 20:55

2 Answers2

4

Yes, there are dozens. You're looking for whats called 'Help Authoring' tools. Many will let you output the content as both a help file and a manual. I'm particularly fond of Help and Manual, but there's quite a few others.

GrandmasterB
  • 37,990
  • 7
  • 78
  • 131
0

I have used Asciidoc for years. I have created a 400 page manual that provides step by step instructions on basically everything my program does (it does a lot but the screen captures tend to expand the page count). Basically you create your documentation in a plain text markup which is quite easy to get the hang of. The big advantages of the plain text markup is that it can be easily added to your version control repository so each version of the manual matches the version of software. It is also easier for other developers to add documentation about new features and bug fixes. In addition, you can create multiple output formats (pdf, chm, html, xml, plain text, etc.) from one set of source files.

I have also found that you can easily compile smaller pieces of the manual. For example I have a section that details the changes and bug fixes for every version that I have released. I had one client ask to see this before purchasing and it was quite simple to write a small configuration file that pointed to the proper sections and then generate a pdf of the release notes only (along with a nice cover page, table of contents, page number, etc.). That has also saved me quite a bit of work when management has asked for that as well - there is nothing like showing them a lot of pages of actual work.

The only issue I have is that it is a little difficult to get running on windows as you have to use cygwin to make it work. There is also Sphinx, on the python side that uses restructured text as the markup language and can do much the same thing. I am planning to test it out on another software project I am involved with. The reason, I am hoping it will be a simpler setup process on windows.

bluebill
  • 151
  • 1
  • 6