Hi,
We would like to prepare the software usage documentation for a web application. This mainly contains the screen shots ( along with relevant documentation ) in most of the pages. Also we would like to have a top menu links using which we can jump to the corresponding pages.
Please suggest the tools which can be useful to fulfill the above requirements.
Thanks, Shafi
I'm sure there's some awesome tool out there that integrates everything needed for usage documentation but I'll tell you what I use!
I use wink to grab screenshots of the application in use. I tend to fire it up and just grab loads of screenshots as I walk through the application, or even just a part of the application. Next, I edit the project in wink to remove redundant screen captures, re-order them and position the mouse on each frame. I then add highlighting which is usually just a nice box around the part of the screen I am demonstrating. Wink allows you to overlay the images with informational boxes and arrows, I then export the project as html and use the numbered, exported png images as the base for my documentation.
I tend to drag them into OpenOffice Writer (or whatever you are using for typesetting) and supplement them with more information - ie a few paragraphs top explain what the user is doing and why.
We use acrobat to output this documentation and providing your table of contents is done properly, it can insert bookmarks in the pdf to enable jumping to relevant sections.
The main benefit we get from wink is that it is very easy to re-grab shots when things change and it can output to flash to provide nice, snazzy demos of small pieces of functionality for posting on the web.
This may be overkill for your project, but I've favored preparing documentation in docbook (xml), since it's fantastically portable/convertable.
To simplify the document creation, you could turn to http://www.oxygenxml.com/, but you can also do the same work in just about any other xml (or even text) editor.
Once your document is prepared, it's trivial to generate html (multi-page, or single page), and pdf versions.
Dr Explain is pretty nice.
It will analyze your page and create a list of controls, buttons, etc. that need callouts.
If you write your documentation with a particular documentation tool in mind, outputting to HTML is relatively simple. LaTex, markdown (with Pandoc in mind), reStructuredText (with Pandoc or Sphinx in mind), AsciiDoc (with DocBook tools in mind) and DocBook (with Docbook tools in mind--see Pandoc).
All of those formats would allow you to easily organize your documentation then export them into HTML however you deem appropriate (probably by major heading, then build a simplistic wrapper around the files). Sphinx can also just output web-based documentation (see Python.org's documentation).
For screenshots I suggest using a standalone app on your platform of choice, Ideally one that lets you do annotation within the program. Skitch for Mac, Jing for Windows, Shutter shutter-project.org or Jing in linux.
Finally I would suggest also doing screencasts as they can be especially helpful to show off the interestingness/power of a web-app.
I don't know what king of language you are writing your code, but in the case of Java, you can use Maven.
With maven you can use many plugins, like JavaDoc, site that create a site with many informations about your API/software and contains the top menu that you want.
This is a screenshot of the site that maven generates: link
I hope these could help!
Cheers
