• Introduction
• Overview
• The Design Plan
• The Documentation Users
• Documentation Types
• Individual Document Outlines
• Layout of Individual Documents
• The Project Plan
• Schedule
• Resources
• Time/Page Estimates
• Cost Estimates
• Conclusions
• Appendix A: User Analysis
• Appendix B: Task List

This plan is designed to outline my proposal for the documentation of the StarCalc 5.0 freeware program. This software is designed for users of the novice to professional astronomy levels, but is most likely to be used by high-school to college age students and adult amateur astronomers. Most users can be expected to have moderate experience with using computers, but will range from novices to experienced users.

The main elements of the documentation set are a beginner's Tutorial, a User's Guide, and a Quick Reference section (which will also include a FAQ, "Frequently Asked Questions"). The alpha and beta drafts of the Tutorial, User's Guide, and Reference sections respectively are: March 23, March 25, April 6, April 8, April 15, and April 20 of 1999. This wide selection of documents will allow effective communication to all levels of users.
 

Overview

The document below outlines in a moderate level of detail the various sections of the documentation set being prepared for the program StarCalc 5.0. In addition to listing the sections and their general content, I have included page estimates, time estimates, and cost estimates for the entire project. The appendix includes a task list and user analysis for the program. The overall goal of the documentation set is to support all levels of users, from novice to experienced computer users, as well as novice to experienced amateur astronomers. Towards that goal, the documentation exists in three main sections: a tutorial, appropriate for inexperienced computer users and astronomers of all levels, a user's guide, appropriate for more experienced computer users who are novices with the program, and a quick reference section, containing a glossary, FAQ, and list of menu commands, appropriate for advanced users. There is also an educational section attached to the tutorial, which explains some of the main scientific aspects of the program.

The Design Plan introduces two main types of users, students and adult amateur astronomers, and details some of their important characteristics as they relate to the software being documented. It also outlines each document, listing publication media and sections, along with approximate page estimates. The layout of these documents is established in the third section of the Design Plan.
 

The Documentation Users:

• High-school/College-age student
• Professional role: student, learner
• Primary tasks: Simulation of star motion (through night and through year), simulation of differences in star locations across the Earth, study of individual star features (brightness, distance, etc).
• Salient Characteristics relating to:
• Information Needs: Academic information relating to stellar distances and spectra, equatorial coordinate system.
• Computer Experience: Intermediate to experienced – students inhabit a wide range of computer experience levels, due to the varying availability of computers at home or in school.
• Subject Matter Knowledge: Novice to experienced – students will come into this program with varying degrees of knowledge, although most will be novice-intermediate level, particularly high school students.
• Workplace Environment: Students can be assumed to be using the program in a classroom environment, with other students and a teacher/instructor/professor available. They will be using the program for a specific purpose within a structured amount of time.
• Learning Preferences: Students are generally conditioned to look to a teacher or instructor, or even other students, for information before going to a manual. In general, students, having been raised in a TV/video game/computer-age, have similar comfort levels for on-screen or print media.
• Usage Patterns: Highly structured time for highly structured activities, but likely the usage pattern as a whole will be haphazard and intermittent.

• Adult Amateur Astronomers:
• Professional role: Anything, more likely to be scientifically oriented, not likely to be a professional astronomer.
• Primary Tasks: Generation and printing of star maps for observing purposes, study of individual star/sky object features.
• Salient Characteristics relating to:
• Information Needs: Procedural guide for obtaining most useful sky maps for observing purposes, lesser concern for academic information concerning detailed star information.
• Computer Experience: Novice to Experienced - Most adult amateur astronomers using this program can be assumed to have some computer experience, because the only way to obtain it is through the web. However, it is most wise to assume that though they have some experience with the web, users may have little experience with learning to use newly installed programs. These users will need procedural guides. And of course, some amateur astronomers will be very experienced with web and computer use. They will be more interested in the FAQ than anything else, given the relatively intuitive interface of most of the program.
• Subject Matter Knowledge: Intermediate to Experienced - Most adult amateur astronomers will understand something about stellar distances and coordinate systems. They can also be assumed to be familiar with the main spectral classifications, though they may not know exactly what they mean or some of the more obscure codes.
• Workplace Environment: Adult amateur astronomers will be working from their homes on their off-time, most likely, rather than in an office setting. As such, they will most likely be working alone to learn to use this program.
• Learning Preferences: Most adult amateur astronomers will be more familiar with print formats, because on-screen reading is a more recent development for the most part. As such, they will be more comfortable with screen-interfaces that resemble print media. (For cost and cross-reference reasons, all files will be in an on-line environment only)
• Usage Patterns: Intermittent use, after the program has been learned.

• Title: StarCalc Tutorial - Getting Started Using StarCalc
• Document Type: Tutorial
• Media: Online

• Title: StarCalc User's Guide: Procedures for Accomplishing Your Goals
• Document Type: User's Guide
• Media: Online

• Title: StarCalc Quick Reference
• Document Type: Quick Reference
• Media: Online

• StarCalc Tutorial - Getting Started Using StarCalc
• Estimated Number of Pages: ~15 units
• Estimated Page Length/Section: ~ 3 screens (a screen being the length of a full-sized viewing window in an internet browser, from top to bottom)
• Getting Started
• What are all those dots on my display screen?
• How can I set the display for my current location and time?
• How do I control what objects are displayed on my screen?
• How can I get a closer look at different areas of the display?
• Finding Information On...
• I see an object I'm interested in. How do I get information about it?
• Where can I find information about the planets?
• Where can I find information on specific stars?
• What does it all mean?
• How far away are the stars? How can I tell?
• How do Equatorial Coordinates work? How are they different from horizontal coordinates?
• What are all these 'magnitudes', anyway?
• What is a color index? What can it tell me about a star?
• There's this thing here called 'spectra'. What do all these letters and numbers mean?
• What do 'binary' and 'spec-binary' mean about the star I'm looking at?

• StarCalc User's Guide: Procedures for Accomplishing Your Goals
• Estimated Number of Pages: ~ 20 units
• Estimated Page Length: ~2 screens
• Orienting Yourself:
• Choosing your observing location
• Choosing your observing time
• Setting your Display Options:
• Changing what objects to display
• Settings for star names, minimum magnitudes displayed, and brightness levels.
• Choosing a grid system:
• Equatorial Grid selection and setup
• Horizontal Grid selection and setup
• Changing your color settings (objects and backgrounds)
• Adjusting which features are placed in front of others (in cases of overlap)
• Viewing your sky
• Zooming in on a region of sky
• Viewing the sky prior or after the original time setting
• Rotating the viewing area
• Autorotation of sky view
• Finding Information On...
• Information on a selected object in sky view
• Information on a known star
• Information on the planets, moon, and sun
• Information on the program/programmer
• Extra Program Features
• Finding plug-ins
• Examples:
• "Color Stars" and "Ecliptic Line"
• "Additional Objects"

• StarCalc Quick Reference
• Estimated Number of Pages: ~ 10 units
• Estimated Page Length: ~ 2 screens
• Glossary
• Actions by Menu
• View Menu
• Time Forward
• Time Back
• Time Now
• Print
• Exit
• Services Menu
• Zoom
• Image Rotation Angle
• Find ðStar by its Proper Name
• Information About...
• Additional Objects*
• Parameters Menu
• Catalogs and Object Groups
• Toggle Autohide Image Adjustment Toolbar
• View Position Toolbar
• Coordinate Grids
• Colors
• Solar System Objects
• Options
• About
• Features on Image Adjustment Toolbar
• Display Star Magnitude lower limit
• Set Star Magnitude Labels lower limit
• Choose Labels size
• Set Number of Brightness levels
• Autorotation Mode
• FAQ (Frequently Asked Questions)

All features will be maintained throughout all three sections of the documentation, for consistency. However, not all features will be used extensively in all sections.

The project plan outlines the production schedule of the above-detailed documents, including final completion dates for the various drafts, reports, tests, reviews, and edits of the documents. It also details both the resources already available for document development, the resources still needed, and total time, page, and cost estimates for the final documentation set.
 

Schedule
 

	Document	Type	Completion Date
Drafts
	Documentation Plan	Alpha	Feb 23 1999
		Final	March 2 1999
	Tutorial	Alpha	March 23 1999
		Beta	March 25 1999
	User's Guide	Alpha	April 6 1999
		Beta	April 8 1999
	Reference Docs	Alpha	April 15 1999
		Beta	April 201999
Tests
	Tutorial	Evaluative	March 23 1999
	User's Guide	Evaluative	April 6 1999
	Reference Docs	Evaluative	April 17 1999
Edits
	Documentation Plan	Technical	Feb 25 1999
	Tutorial	User	March 23 1999
	User's Guide	User	April 6 1999
	Reference Docs	User	April 17 1999

Resources

Personnel resources I have available include, aside from myself as documentation developer, my current classmates in English 418: Software Documentation, and the professor of said course, Dr. Stuart Selber, as technical and content reviewers. I have also made contact with the developer of the program, although he did not express any interest whatsoever in making use of my documentation set when distributing his program. Furthermore, several Penn State students who are unconnected with English 418 have agreed to proof-read the user documents in terms of comprehensibility, when they are in the Alpha draft stage.

Computer and equipment resources I have available to me include the CAC labs at Penn State University, which supply middle-line PCs and Macintosh machines (standard programs including MS Word, Netscape Navigator, and Eudora Light), scanners, and high-quality black-and-white printers. My own personal PC is a 166 MHz Pentium with a color ink jet printer. Programs currently installed on my machine include Netscape Communicator 4.5 and MS Word 97. I currently have 5 MB of web storage space available to me:

• 2 MB on Penn State's personal server (www.personal.psu.edu/users/kjk176)

• 3 MB at StudentAdvantage.com (http://webcreator.mainquad.com/users/kjk176/index.htm)

Time/Page Estimates
 

Document	Number of tasks/topics	Average # of  hours per task	Total Hours
Tutorial	13	3.5	45.5
User's Guide	19	2.9	55.1
Quick Reference	25	1	25
		Total Hours for Project:	125.6

Cost Estimates
 

Item	No.	Cost/Item	Total Cost
Paper pages	6	$ 0.10	$ 0.60
Internet connection	1	Free	Free
Web space	5 MB	Free	Free
GIF Movie Gear Registration	1	$ 30.00	$ 30.00
		Total Cost:	$ 30.60

The documentation outlined above is for the freeware software program StarCalc 5.0. Designed as a complete online help system, it consists of a beginner's Tutorial, a User's Guide for intermediate users, and a Quick Reference file for more advanced users. The completion dates for the documents are set through March and April, and the resources to complete them are available. With approval of this plan, documentation development will begin.

Back to main Help page