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.

This question focuses on user documentation, not on code documentation.

I just finished my software project, and the people I work for are expecting me to write user documentation, describing everything the software does.

All the documentation they had until now (about the rest of the software they use) is full of screenshots, and sometimes barely contains any text. I think it's awful. I've been struggling for hours to understand how screenshots were connected, and most of the time I had to ask for help from someone else.

I wrote a Java desktop application, and its appearance is likely to depend on the current Windows theme and Java update. I don't think screenshots can form reliable, definitive reference.

Taking hundreds of screenshots and annotating them will take forever, and I don't believe it will help more than accurate, plain text documentation.

How should I approach putting the user documentation together? What guidelines should I follow regarding the use of screenshots versus explaining in text with user documentation?

share|improve this question

marked as duplicate by Dan Pichelman, MichaelT, Ozz, ChrisF Sep 25 '13 at 11:32

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

7  
nearly every how-to manual contained screenshots or was very well designed so users can find the referenced GUI elements easily, pick your poison –  ratchet freak Sep 16 '13 at 13:23
2  
its appearance is likely to depend on the current Windows theme - use the default theme. with Aero switched off, it looks roughly the same for Windows Vista/7/8 –  Konrad Morawski Sep 16 '13 at 13:24
    
@KonradMorawski Indeed, but window decorations will still depend on the chosen theme (even if it doesn't make screenshots unusable, of course). –  Aeronth Sep 16 '13 at 13:30
    
Thank you for correcting this question! –  Aeronth Sep 16 '13 at 14:10
3  
It sounds to me developers of the other apps did just exactly what was asked: show everything the software does. Hardly useful, but then again, you shouldn't ask a developer to produce user documentation anyway. The mind models of the writer and the reader are just too different. Last Saturday I worked on my brother's Mac and asked "what is the keyboard shortcut to get to the beginning of the line?" He said he didn't know. Frankly he didn't even know what a keyboard shortcut is. Turns out he always uses the mouse to get to the beginning of a line. And that would never have occurred to me... –  Marjan Venema Sep 16 '13 at 15:12

4 Answers 4

up vote 13 down vote accepted

Screenshots are an important aspect of the user guidance. However, they also need to be accompanied by clear and precise instructions. For example, having a screenshot showing the screen, a red arrow pointing to a button and the text reading 'Now that you have entered the filename, Click the Next button.' is much clearer than either the text or the screenshot alone.

Doing good click by click guides is time consuming, but worth it when it comes to supporting end users (even technical ones)

share|improve this answer
    
I don't think click-by-click screenshots are necessary, but screenshots with arrows or other highlights to call out what's being discussed are a really good idea. –  Bobson Sep 16 '13 at 14:04
    
If you are likely to either have to follow the instructions in 18 months time, after not having worked on this part of your product, or have to support more than a few end users, then putting in time and effort up front, when you can plan for it, rather than having to put in a similar amount of effort at unplanned times when you have an irate customer on the phone is a good trade off. 18 months later you will be glad of all the extra information –  Ptolemy Sep 16 '13 at 14:23
    
I was more thinking that one screenshot could cover multiple clicks, rather than each click getting its own image. Or summarize like "Fill out these 8 fields, then click Next" with a circle around the block of fields and another around the Next button. Sometimes it's easier to take in information in larger related chunks. –  Bobson Sep 16 '13 at 14:33
    
Yeah, I often do that. On the screen shot, I'd show all the information filled in. –  Ptolemy Sep 16 '13 at 14:37
1  
Please do include screenshots in your documentation, even if many users will see slightly different chrome on their windows. As a MacOS X developer I was one of the people who convinced an Apple Engineer to put screenshots (Command-Shift-3) back into MacOS X for documentation. –  Michael Shopsin Sep 17 '13 at 15:13

The old adage "a picture tells a thousand words" is rarely as important as it is here. Please, please, please, for your sake and for your users: USE LOTS OF SCREENSHOTS.

Having been in a similar situation, where most of my users were elderly women, I cannot convey how useful screenshots are. The question becomes, how to present them. I found that a task-based approach works best.

e.g.

Table Of Contents

  1. Customer Information
    • I want to update a customer's address
  2. Billing
    • I want to create an invoice for a customer
    • I want to create a bill for a customer
  3. Shipping
    • You get the idea

Note that each heading in the TOC is obviously a link (which any format, be it word/html/chm/whatever supports). Then for each individual action (eg. 1.1) start with the first screen the app shows when it opens up.

  1. Start at the Home screen
    • [screenshot]
  2. Click "Customers"
    • [screenshot with big red circle around "Customers" button]
  3. You arrive at the Customers window
    • [screenshot of the customers window]
    • (note, use a test build with only fake customers)
  4. Click "Search"
    • [screenshot with big red circle around "Search" button]
  5. Enter the customer's last name and double-click their name
    • [screenshot of the search window with the customer's lastname in the search box]
  6. You arrive at the customer details screen
    • [screenshot of the customer details]
  7. Click "Edit"

etc.

Yes, this first few steps are redundant, and the whole thing is lot of laborious screen-shooting. Users will get used to just flipping past the first page or two but anyone and everyone, on their first day on the job, or after a long vacation, or mat leave, or sick leave, or whatever... can be told to "Go do [this]" then click "I want to do [this]" in the docs and have detailed instructions showing exactly what to do.

You can have the first step be "Open the customer's file" which is linked to the "I want to see a customer's information" section. Be wary, I switched to that, and had a large portion of my users that found this extremely complicated. The ones who didn't find it complicated, didn't care enough to appreciate the 'shortcut'. The tip is: Know your audience and don't assume anything about them.

There's an old article from Joel Spolsky (that, for the life of me, I cant find) where he talks about usability and the wheelchair assistance bars in bathrooms. The crux of the argument was that some usability features aren't necessary for everyone... but when available, everyone uses and appreciates them. I firmly believe that incredibly obvious documentation for internal apps fits in this category. Especially considering that they can't be searched for help online.

share|improve this answer

It depends on your precise application and how it's structured, but in general you should have more text than screen shots I've found. Unless your product will be a user's first introduction to a computer, you shouldn't worry about click-by-click instructions. Assuming your user interface is sane, you should be able to describe how to do most operations with text and maybe a few screenshots.

If, your user interface isn't quite sane and/or is misleading.. well, you could fix that, or you could give screenshots or even animated GIFs showing how to actually get your product to work. You should provide this in addition to a lot of plain text though.

share|improve this answer

Are the users likely to be programmers/tech people themselves, precise description with only a few screenshots should be sufficient.

But if the users are non-tech people screenshots with precise descriptions will help a lot. Keep in mind most people are not even aware of the technological terms you are probably using in your description. Try to ask any person using a computer what a radio button is.

Bottom line: Depends on your users

share|improve this answer

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