Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Snap shots in the User Guide?

 
christy smile
Ranch Hand
Posts: 101
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi, All,
I am writing the user guide. I would like to know how many snap shots should we provide for the user guide? I think I am having a lot since I have a GUI for the server, which I provided one for the stopped, one with information filled in but still at the stopped state, and another snap shot in its running state. Is it too much? Thanks.
Christy
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Christy,

I am writing the user guide. I would like to know how many snap shots should we provide for the user guide? I think I am having a lot since I have a GUI for the server, which I provided one for the stopped, one with information filled in but still at the stopped state, and another snap shot in its running state. Is it too much?

I had both client and server too and had quite a few screen shots myself (20 for the client and 16 for the server). The real question is do you think it's too much? Your user help should be clear enough for even those users that barely fit the profile of primate, you know, the one's the make developer's lives hell.
Michael Morris
 
Pete Lyons
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I'm not planning on having any screenshots. Remember that this is java, and the program will look very different on Windows, X Window, and Mac OS X. Unless you are going to have at least 3 separate versions of the screenshots for each common look and feel, having a screenshot of a different LnF (from what the user is seeing) could be confusing. I'm just relying on how clearly I labeled all of the UI widgets.
I'm also not going too crazy with the help because:
-In my experience, only a very few advanced users actually use and read online help, in which case they will have few if any trouble using this application. The truly helpless (no pun intended), always ask another person to show them how to do something.
-Having developers (especially the same ones who wrote the software) write user manuals is BAD BAD BAD. Javadoc, yes. User help, no.
 
Thomas Fly
Ranch Hand
Posts: 164
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I'm inclined to differ- since this is Java, screen shots should look essentially the same on different platforms; the L&F differences shouldn't be too upsetting to anyone that has any business turning on a PC.
Of course, a lot of people who shouldn't use PCs do (or try to), just like guns, cars, brains, etc.
 
Pete Lyons
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Well, if you do do screenshots, I would grab the windows LnF as Mac and Unix users will be accumstomed to seeing that in documentation. User doc counts for 10 points, which seems odd to me since all that javadoc is only worth 5 points, but I still feel I'll be OK with just a clear interface, good tooltips, and simple explainations ("basic user documentation"). This app is very simple. We'll see what happens when I submit my assignment.
 
Thomas Fly
Ranch Hand
Posts: 164
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
If the average user can't figure out how to use the application, then it's irrelevant how brilliantly or stupidly it's designed & implemented- thus the importance of user documentation.
And you're right about using Windows (if possible) for your screen shots. I use SnagIt- which is a wonderful program that's good for more than just screen shots.
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Unless you are going to have at least 3 separate versions of the screenshots for each common look and feel, having a screenshot of a different LnF (from what the user is seeing) could be confusing. I'm just relying on how clearly I labeled all of the UI widgets.

Excellant argument for using the metal LnF.

Michael Morris
 
Thomas Fly
Ranch Hand
Posts: 164
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Too much trouble- and I don't have any paint remover.
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I would still recommend using some screen shots. Just explain in the user documentation that the actual GUI on various platforms may vary.

Michael Morris
 
Pete Lyons
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Alright, I guess I will take a few screenies of the Windows LnF on the client (server is a console only daemon). But only because I tested and found that JEditorPane will show them without me having to write any more code.
Thomas, thanks for the link to SnagIt.
Michael, 20 screenshots?!?! My gui doesn't have 20 widgets! If you need a screenshot to understand "To exit the application, choose 'Exit' from the 'File' menu", you need basic computer training that me as (begrudging) documentor of this app should not have to provide you. Should I explain in agonizing detail how a checkbox works, or that after you've brought up a menu, clicking somewhere off the menu hides it?
Sorry - just blowing off some steam. Every time I think I'm ready to turn in this puppy, one more thing pops up. 20 screenshots ... aye aye aye.
 
Michael Morris
Ranch Hand
Posts: 3451
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Pete,

Michael, 20 screenshots?!?! My gui doesn't have 20 widgets! If you need a screenshot to understand "To exit the application, choose 'Exit' from the 'File' menu", you need basic computer training that me as (begrudging) documentor of this app should not have to provide you. Should I explain in agonizing detail how a checkbox works, or that after you've brought up a menu, clicking somewhere off the menu hides it?

I probably went too far, but I have had many bad experiences with users that had a hard time remembering their own names. I don't think it necessary to describe how primative components work, we have to assume that our users know the basics. I did explain about accelerators and ALT+ key sequences to access menu items.
Michael Morris
 
Thomas Fly
Ranch Hand
Posts: 164
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I have screen shots in my docs- but alas the metal is no longer visible
I can't imagine why the assessor would have any problem running my app, but one thing the screen shots do is show that I, at least, was able to get it to go, and what I intend it to look like.
 
christy smile
Ranch Hand
Posts: 101
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi, Pete, Michael, Thomas,
Thank you for replying!
Here are more stuff that I would like to have your feedbacks
quot:
-------------------------------------------------------------
Every time I think I'm ready to turn in this puppy, one more thing pops up.
--------------------------------------------------------
I had exactly the same feeling! The closer I get to turn this in, the more nervous I get, then, I change more stuff
I actually consulted someone that has been doing GUI design professionally today about my GUI design. She gave me so many recommendations I kind of regret that I have gone to her because now I have more code to change
Here are a couple things she has suggested which I am not sure if it is worth the effort to change:
(1) For the entry fields for the searching criterias, I used comboboxes. But those comboboxes are empty when the GUI first starts. As user enter in the criteria, it compiles a history list for the criteria during the session. However, she suggested that I should fill the comboboxes with the appropriate information from the database when the GUI first comes up. e.g. For the comboBox for the Origin Airport, I should fill it with all the Origin Airport for the flights in the database. Is this necessarY??
(2) I provided a Reset button that clears all the entry fields for the criteria, she said that it is not neccessary, and if I insist on using it, I should rename it to "Clear". What about that?
(3) "Book" button for making reservation is not obvious. Need a better name for it. In addition, my current design is to have the user click on a desired flight in the table, then either click on the Book button or double click on the flight to book the flight. She does not think that is obvious for the user to use the application. I need someway to explain the process to the user (and the on-line help is not the right place to explain since a lot of user don't go to the on-line help at all). What is your design for the booking function?
(4) She suggested a possible status bar for the client GUI to prompt the user for possible actions at certain state. How about this?
There are a dozen other suggestions I am still sorting through. Your comments are welcomed!
Thank you
Christy
 
Pete Lyons
Ranch Hand
Posts: 109
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Christy,
1. This is a good idea, which most of us did, I think.
2. I agree with your friend on that one
3&4. I used a status bar to provide feedback to the user about various things. Also tooltips can help a lot. I also personally like to put titled borders around panels of related widgets with code like

...although I have not seen too many others do this.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic