Book II 9 in Java

Painting Quick Response Code in Java Book II 9

Many programmers prefer using agile documentation methods Just as agile programming means being able to adapt to changing conditions, agile documentation means updating the documentation just enough to be accurate but without wasting time trying to make it perfect

Computer scientists have developed special documentation generators that can examine source code and create simple explanations for how different parts of a large program works By using such automated tools, keeping documentation updated is much faster and easier than forcing a reluctant programmer to write and update documentation manually After documentation has been partially completed with an automated tool, the programmers can edit the documentation to keep it up to date

Partially to avoid writing and printing manuals that few people bother to read anyway, programmers are writing help files instead Help files essentially condense the user manual into short explanations that give users three options for finding help by Browsing through a table of contents of logically organized topics Searching an index for specific commands or topics organized alphabetically Searching for specific terms or phrases

Help files can be read like a book, browsed through like a dictionary, or searched like a search engine that returns pages of related information Like ordinary user manuals, help files often require the aid of programmers to explain and verify that the explanations in the help files are accurate and complete To make creating help files easier, many programmers use special help file creation programs, which can turn an ordinary user manual into a help file By using such tools, programmers don t have to create user manuals and help files separately; they can just create a user manual and then turn that user manual into a help file Ultimately, any form of documentation is meant to help explain what a program does and how it works When writing documentation for your program, make it easy on yourself and write as little as possible while trying to be as complete as possible It s not an easy task, but it s a necessary one

Following the evolution of user interfaces Defining the elements of a user interface Designing a user interface

ou can divide every program into two parts: a user interface and the part of the program that actually does something useful, such as predicting winning lottery numbers or editing video images The whole purpose of a user interface is to give a program a way to Accept commands from the user Accept data from the user Display information back to the user The user interface basically lets you give information to a program and receive useful information back again, as shown in Figure 10-1 Most user interfaces let people control a program, but a user interface can just as well let inanimate objects (like a motion detector) control a program Without a user interface, you can t control a program or retrieve any useful information from the program

Figure 10-1: The user interface lets you control a program, give it commands, and retrieve useful information back

To better understand user interfaces, you need to know how user interfaces evolved and how current user interface designs are meant to solve the problems of the past

In the old days, programmers focused on writing the useful part of their program and then as an afterthought, they created a simple user interface for controlling that program Because the programmers already know how to control their own program, they often create a bare-bones user interface that looks as confusing as this:

At this point, the user is supposed to know not only all possible valid commands to use, but also how to spell and use each command as well Such bare-bones user interfaces are command-line interfaces because they force users to type in commands one line at a time The problem with command-line interfaces is that they re too hard to use: You have to know all valid commands you can use You have to know what each command does so you know which one to pick You have to type each command in correctly Spell a command wrong or leave out a space, and the program rejects that command and makes you type it all over again