Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

End user documentation on how to use applications is an important part of the user experience of applications, irrespective of whether they are winforms, wpf or even asp applications.

In a startup or internal development team situation, where there isn't a dedicated documentation department, it can take a lot of resources to maintain screen shots and associated user documentation, such as on-line help or even printable manuals.

What tools are available to assist in creating screenshots of all the "screens" within an application (be they winforms, wpf or aspx) to help automate the capture of screen shots, and associating with the relevant documentation?

In addiiton, are there any that allow automation of annotations of a particular control (so use cases like: Draw a red box around the Username control with a callout to say "This is where you'd enter your user name, in the form 'firstname.surname@example.com'")?

share|improve this question
3  
That's called magic. –  ChaosPandion Feb 10 '11 at 17:30
1  
@ChaosPandion I've seen similar magic when I was doing some stuff in C++/ATL, so I might be lucky - if not, it's one heck of a product idea for the likes of Fog Creek :) –  Rowland Shaw Feb 10 '11 at 17:40
9  
Unpaid interns... –  sdg Feb 10 '11 at 17:53
add comment

closed as not constructive by Jim G., Robert Harvey, gnat, MichaelT, Martijn Pieters Mar 7 '13 at 8:30

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.If this question can be reworded to fit the rules in the help center, please edit the question.

7 Answers

I don't know of any automated tools as such, but this is too long to put in a comment.

I'd strongly suggest starting a wiki for your project to hold user documentation. Then you can quickly draft a overall view, and gradually expand on it. Make it a requirement that when someone changes something that affects the end-user, they update the documentation to reflect this.

Have a "help" button on each widget in the interface that opens the users web browser to the relevant page on the wiki. This will gradually lead to you having an idea of which help pages people look at most (from web server logs), and so you can work on making the interface more intuitive and know where to focus your documentation efforts.

I agree with @Jim C and @nikie - don't expose your users to technical details. They don't care. What a user wants to know when they click on the help button is how to do what they're trying to accomplish.

share|improve this answer
    
I completely agree that the on-line help and user guides need to be task-focused, rather than just regurgitating what the applications do. I would worry with the level of technical expertise that my end users have, that they may struggle with the concept of a wiki, and we'd still need to generate a lot of stub information anyway, which partly what this is about. I'm sure there used to be tools for generating on-line help giving .chm files, content for websites and even printable documents from a single source. I just can't remember what it was called... –  Rowland Shaw Feb 10 '11 at 18:46
    
If you have a single wiki, how do you cope with different users that use different versions? Or users who work on a machine with no internet connection? A document file can be kept in your source repository alongside the source for the version it applies to. A tag then knows what the manual said for a particular release, as well as what the source was. I particularly like plain-text files that can be processed to PDF or whatever for this - LaTeX, DocBook, HTMLDOC and others. Doxygen can even be "abused" for this - it doesn't have to include anything generated from code. –  Steve314 Aug 5 '11 at 10:25
add comment

Have you tried RoboHelp. I've had a chance to work on that and its an awesome tool. There is a cost involved there though.

share|improve this answer
    
Looks interesting. Could you provide some more detail? I'm having trouble breaking the marketing barrier to figure out exactly wtf it does/how it works. –  Steve Evers Apr 11 '11 at 22:02
1  
Its been quite a while since I used it so not sure if I can give you any details rightaway. The link provided takes you to the site where you can find some case study as well a video. If you;re looking for anything specific, let me know and I'll see what I can do. –  hangar18 Apr 12 '11 at 16:59
    
I've been looking into it a bit more and it looks much more capable than I originally thought. Thanks. –  Steve Evers Apr 12 '11 at 17:28
add comment

I use Asciidoc for generating my documentation. All you do is edit plain text files and then compile them. They compile to pdf, chm, xhtml and some others. Images are treated as simple links in the documentation and added at compile time. So if a screen capture changes, just replace the file and re-compile.

The only thing I don't like is that you have to install cygwin on windows to get the tool-chain up and running. Other then that it is excellent and very compatible with version control In addition you can break your documentation up into smaller text files (i.e. text files for different areas of your application).

For example I have created a 400+ tutorial (mostly screen captures) for our main software package. From that source code I am able to generate a full pdf and a chm file. In addition I also keep release notes so that I can create a separate pdf file in addition to merging them into the main chm file. There is a bit of a learning curve - but it is worth it.

share|improve this answer
    
For screen captures I toyed around with the idea of building a special mode that loaded each form and populated it with sample data then took a screen capture. In the end it is easier to take a screen capture manually and annotate it properly (arrows, highlight boxes, etc.). –  bluebill Oct 3 '11 at 21:31
add comment

One approach is to avoid screen captures like the plague. They are obsolete almost immediately. Instead, focus on concepts. Nail down your terminology and use abstract diagrams and mock-ups rather than screen caps.

Here's an interesting looking tool for creating mock-ups. One of our business analyst guys says he loves it.

share|improve this answer
11  
Screen captures do become outdated as code changes, but most people are visual learners. If you don't show them, they don't understand. –  Jim C Feb 10 '11 at 18:06
4  
-1. I hate manuals like that. Even a slightly obsolete screenshot (e.g. with one missing button) is immediately recognizable. With a pure text description, I don't even know if I'm reading the manual to the right form. –  nikie Feb 10 '11 at 18:12
1  
Given that this question is about automated tools anyway, the solution is quite easy: regenerate the screenshots during your CI build. Assuming, of course, that such a tool actually exists, which, unfortunately, doesn't look likely based on the current answers. –  Jörg W Mittag Feb 10 '11 at 18:24
    
@Jim, I'm not saying don't use pictures. They just don't need to be screen grabs. –  Ishmael May 12 '11 at 19:28
add comment

All windows in Windows (even the WPF ones) are still controlled using win32 messages, and you can still install a global hook.

So, if you write an app that installs a post-processing windows hook that traps all WM_CREATE calls (you might need WM_INITDIALOG) then its possible to take a snapshot of the created window immediately after its created. If this goes too fast, you could pause a second to take the capture, which would be ok as you're only running this occasionally for documentation purposes.

You'd probably want the CBT hook. I don't know of a screen capture lib, but the co-ordinates of the windows will be available in the hook callback.

share|improve this answer
add comment

I am a .NET developer and I have never heard of anything like this that will generate documentation for you; I honestly don't think that it exists but I could be very wrong. We don't have a dedicated documentation department either and unfortunately it's left on my shoulders usually to write the docs and help systems. It's actually not that bad once you get some decent tools to help you along the way. I am a big fan of the MadCap family of products for creating decent help and user docs. for the screen capture stuff, I use the Capture application that comes as part of the suite and Mimic is a pretty good way to create an interactive tutorial.

share|improve this answer
    
I'm not asking for it to do the documentation for me, just assist with the dull tasks like screen caps, and maybe allow annotations on those - I have used something like that in the past (I believe it also did part of the QA to assist checking things hadn't moved/gone missing), but I forget what that tool was (and even then, it was in an ATL environment, rather than .Net) –  Rowland Shaw Feb 10 '11 at 18:39
add comment

Just saw a demo from a company called Epiance - they have a product called XYdocs that pretty much does what you described... creates a detailed dump of actions along with the corresponding screen images and callouts that tell the user what to do. You can then edit and publish to .doc, .pdf, html, etc...

share|improve this answer
add comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.