To Kara's Homepage
For my software documentation project, I worked with the freeware program StarCalc (version 5.0), a sky-mapping and information program. Although the program is usable by beginners, I found that it was more suited to the informational needs of the advanced amateur astronomer, and so I had a large range of users to design for. Also, though I could assume that all program users were at least passing familiar with the Internet (because the program is only available over the Internet), I had to write for a broad range of computer experience on the part of the users. This is because, though most of them would obtain the program by themselves over the Internet, some might be using the program as part of a class, and so could not be assumed to be experienced with computers.
Each section of the Manual is, of course, designed for a different level of user. The Tutorial, perhaps the most difficult section to design, is for beginners. The User's Guide is designed for either novice users who have already worked through the Tutorial, or for more experienced computer users who want a step-by-step guide their first time through a procedure. The Reference Guide is for an entirely different class of user. Most users of the Reference Guide are experienced computer users and astronomers who, with a minimum of guidance to get them started and to work through some of the more esoteric labels, are perfectly capable of figuring out the program and using it effectively on their own.
Despite the fact that the three documents are designed for very different types of users, I chose an on-line format for all of them. There were two main reasons for this. First, StarCalc is an extremely modular program. Once a user has opened the program, and set his viewing location and time, there is no set, logical progression of steps he needs to take, no "open"-"type"-"save"-"close" type of pattern. Each feature in StarCalc exists as a total entity unto itself and can be used either separately or in conjunction with every other program feature. A print manual, even if it has a table of contents that allows the user to skip sections he isn't interested in, by its very nature implies a chronological progression of steps from start to finish. A person can flip to a section in the back of the book to figure something out, but to get there, he has to page through all the other sections. In an on-line format, that feeling is eliminated - once in the section you're interested in, you can select and link from the list and view it without ever having to look at any other section of the guide.
This format worked very well and very easily for the User's Guide and the Reference Guide, as these sections are inherently modular anyway - as a writer, I could assume that people using these sections were looking for procedural help and already knew what basic information they were looking for. In the Tutorial, a user who is totally lost is more likely to become more lost than less if he tries to move through the Tutorial out of order. However, there are a range of users possible even for the Tutorial - for instance, most users would know what a constellation is, and want to skip that section of the academic tutorial, but there could be few who do not, and who will be totally lost in the program without that basic knowledge. I wanted to provide these more advanced beginners with some way to move through sections of the Tutorial without having to page through all the previous sections. However, there is also another reason for this format, which is very applicable to the Tutorial.
All of my documents are designed to be used in conjunction with the program, rather than being read beforehand and then later applied on the computer. This is based on the observation that retention tends to be very poor for material which is simply read and not interacted with. My reasoning was that if they had the program open while working through the Manual sections, they would remember more of the process. It would also be a more time-efficient process - users would not have to be constantly running between a book and a computer screen. Putting the Manual on-line seemed a perfect way to avoid the problems and the discontinuity caused by working between a book and the computer screen. Judging from the reactions of both classmates and my professor during testing sessions, this interaction between the program and the Manual has proved effective. Users tend to toggle back and forth between the two screens, learning the program, commands, and buttons with little effort.
Once the decision to put everything on-line was made, other considerations came to the fore. For each section, issues of both style and format, as well as content, were a concern. I did standardize my page formats, reasoning that for users that would work through all three documents, a recognizable, consistent format would make the learning curve just that much quicker, requiring less readjustment for the user, even for purely aesthetic issues like background and hyperlink color. I therefor used the same background (a star field, appropriately), the same horizontal lines, and included links back to my homepage and to the next hierarchical level (from a Tutorial page back to the Tutorial Table of Contents, for instance) a the bottom of each screen, all in a one-column layout. (On-line, it is difficult to standardize column widths without using frames, which not all browsers support, so I decided to keep everything in a vertical, one-column format. Since many of the more novice computer users would not be accustomed to frames and would not know what to do if their browser didn't support them, I felt this decision was clear on the basis of my user analysis.)
In each individual section of the document, there were specific issues to address as well. Conventions regarding color and text style were easy to standardize, essentially on the grounds of contrast and what was noticeable to the eye. Content and other similar issues had to be dealt with individually for each document.
In the Tutorial, I had a very specific content issue to address - how much did I want to assume that my users knew about astronomy in general? I realized that I really had two very different populations of users accessing my Tutorial - a group of users who were generally younger, computer-savvy, but not very experienced in the world of astronomy, and a group of users who have been doing at least observational astronomy for years, but who are not very experienced with computers in general. Essentially, my final Tutorial design reflected this. There are two sections, the first outlining procedures, the second an academic tutorial explaining some of the basics of astronomy. Although the two are interconnected to an extent, the on-line setup allows users to access whichever half suits their needs more closely.
The other main issue in the Tutorial was language. The audience the Tutorial is aimed at mostly consists of novice program users who are also novice astronomers, so a technical approach was not appropriate. The worst thing about most science writing - and most science documentation - is the dry, formal tone, which tends to alienate novices and younger readers. The tone couldn't be too chatty, because of efficiency concerns, but too formal a tone also tends to sound very program-oriented, and in the Tutorial most of all, the writing needed to be accessible, task-oriented. The tone I finally ended up with is friendly and accessible, avoiding program-centered language.
The User's Guide introduced a different set of considerations. Here the issue was more how could I best guide users to the procedure they actually wanted? Keeping my procedure titles - and indeed, the procedures themselves - short and concise, so they were readable, but still detailed enough so that people could actually understand what they were, was the main concern. Much of the explanatory detail that was necessary in the Tutorial could be dropped, because I could assume that the user had sought out the procedure already knowing why he wanted to use it. However, the procedures had to be just as detailed, because many slightly more experienced computer users will skip a Tutorial on general principles and move right to a User's Guide, even though they are still very unfamiliar with a program.
The Reference Guide is a very different kind of document than either the Tutorial or the User's Guide, which are much more closely related in terms of who is accessing them. The Reference Guide is aimed at users who may not have ever looked at either of the other documents before opening the Reference Guide, and who are either expert astronomers with at least an intermediate level of computer experience, or expert computer users with at least an intermediate level of astronomy knowledge. This class of users is more accustomed to working with programs and mainly want to know what the program can do for them, and how they can get it to perform the task in the quickest, most efficient way.
For this reason, the tone and character of the Reference Guide had to be totally different from the other two. Although still task-oriented and informative, the Reference Guide cuts out all of the unnecessary verbiage and delivers a clear, but very concise, product. It also adopts a more business-like, less conversational, tone, and is somewhat more program-oriented than the other two documents. The reason for this is as I stated above: the users, at this level, are looking to find out what the program can do for them, or are looking for the quickest possible way to do something inside of the program, and so are best served by a more program-oriented outlook. These users are also more accustomed to reading the older style reference documents produced for computers, which were program-oriented in the extreme, and so are not put off, and in fact may even be expecting, this kind of an orientation.
Because these documents were on-line, my graphics had to be handled differently than in a print medium. They had to be larger, because the resolution on the user's screen could not be counted on to be high enough to support the re-scaled graphics that you can place in a printed page. Each screen shot is almost full size, therefor - at most, they were reduced to 75% of their original size. However, I also had the option of using image-maps, a way of allowing the user to access different parts of the documentation via a graphic, rather than typed hyperlinks. This, I found, was very useful for users, who could relate better to an exact copy of what they were seeing on their program screen than to a typed-out version approximating what they were seeing. I used several image-maps in the Tutorial, and my main Reference documentation is based on an image-map. The image-map was especially applicable in that situation because the users are looking for explanations of specific program functions and buttons, and reminders of how to perform specific processes.
All in all, the absolute most important consideration throughout designing
the documents was making sure that the appropriate user level at each section
of the documentation was being satisfied by the tone and content of the
documentation at that level. Design the documents with what the users want
in mind, and you as the writer will be able to give them what they need,
even if they don’t already realize exactly what that is.
