Download UML and Software Documentation: Understanding Different Types and Tools and more Study notes Electrical and Electronics Engineering in PDF only on Docsity!
Appendix 3
UML and Software Documentation
Software Documentation or Source Code Documentation is written text that accompanies computer software. It either explains how it operates or how to use it. In fact, the term software documentation means different things to different people. This article describes the term as used by the largest groups of users.
Relationship to hardware
Computer software is so called in contrast to computer hardware, which encompasses the physical interconnections and devices required to store and execute (or run) the software. In computers, software is loaded into RAM and executed in the central processing unit. At the lowest level, software consists of a machine language specific to an individual processor. A machine language consists of groups of binary values signifying processor instructions (object code), which change the state of the computer from its preceding state. Software is an ordered sequence of instructions for changing the state of the computer hardware in a particular sequence. It is usually written in high-level programming languages that are easier and more efficient for humans to use (closer to natural language) than machine language. High-level languages are compiled or interpreted into machine language object code. Software may also be written in an assembly language, essentially, a mnemonic representation of a machine language using a natural language alphabet. Assembly language must be assembled into object code via an assembler.
Architecture/Design Documentation
Design documents tend to take a broad view. Rather than describe how things are used, this type of documentation focuses more on the why. For example, in a design document, a programmer would explain the rationale behind organizing a data structure in a particular way, or would list the member functions of a particular object and how to add new ones to the code. It explains the reasons why a given class is constructed in a particular way, points out patterns, and even goes so far as to outline ideas for ways it could be done better, or plans for how to improve it later on. None of this is appropriate for code documents or user documents, but it is important for design. Architecture documentation is a special breed of design documents. In a way, architecture documents are third derivative from the code (design documents being second derivative, and code documents being first). Very little in the architecture documents is specific to the code itself. These documents do not describe how to program a particular routine, or even why that particular routine exists in the form that it does, but instead merely lays out the general requirements that would motivate the existence of such a routine. A good architecture document is short on details but thick on explanation. It may suggest approaches for lower level design, but leave the actual exploration trade studies to other documents. Another breed of design docs is the comparison document, or trade study. This would often take the form of a whitepaper. It focuses on one specific aspect of the system and suggests alternate approaches. It could be at the user interface, code, design, or even architectural level. It will outline what the IS situation is, describe one or more alternatives, and enumerate the pros and cons of each. A good trade study document is heavy on research, expresses its idea clearly (without relying heavily on obtuse jargon to dazzle the reader), and most importantly is impartial. It should honestly and clearly explain the
costs of whatever solution it offers as best. The objective of a trade study is to divine the best solution, rather than to push a particular point of view. It is perfectly acceptable to make no conclusion, or to conclude that none of the alternatives are sufficiently better than the baseline to warrant a change. It should be approached as a scientific endeavor, not as a marketing technique.
Technical Documentation
This is what most programmers mean when using the term software documentation. When creating software, code alone is insufficient. There must be some text along with it to describe various aspects of its intended operation. This documentation is usually embedded within the source code itself so it is readily accessible to anyone who may be traversing it. This writing can be highly technical and is mainly used to define and explain the APIs, data structures and algorithms. For example, one might use this documentation to explain that the variable
m_name refers to the first and last name of a person. It is important for the code documents to be
thorough, but not so verbose that it becomes difficult to maintain them. Often, tools such as Doxygen, javadoc, ROBODoc, POD or TwinText can be used to auto- generate the code documents—that is, they extract the comments from the source code and create reference manuals in such forms as text or HTML files. Code documents are often organized into a reference guide style, allowing a programmer to quickly look up an arbitrary function or class. Many programmers really like the idea of auto-generating documentation for various reasons. For example, because it is extracted from the source code itself (for example, through comments), the programmer can write it while referring to his code, and can use the same tools he used to create the source code, to make the documentation. This makes it much easier to keep the documentation up-to-date. Of course, a downside is that only programmers can edit this kind of documentation, and it depends on them to refresh the output (for example, by running a cron job to update the documents nightly). Some would characterize this as a pro rather than a con.
User Documentation
Typically, the user documentation describes each feature of the program, and the various steps required to invoke it. A good user document can also go so far as to provide thorough troubleshooting assistance. It is very important for user documents to not be confusing, and for them to be up to date. User documents need not be organized in any particular way, but it is very important for them to have a thorough index. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do and should be free from undocumented features. There are three broad ways in which user documentation can be organized. A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks. A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user. The final type of organizing principle is one in which commands or tasks are simply listed alphabetically, often via cross-referenced indices. This latter approach is of the greatest use to advanced users who know exactly what sort of information they are looking for. A common complaint among users regarding software documentation is that only one of these three approaches was taken to the near-exclusion of the other two It is common to limit provided software documentation for personal computers to online help that give only reference information on commands or menu items. The job of tutoring new users or helping more experienced users get the most out of a program is left to private publishers, who are often given significant assistance by the software developer.
describes information that is passed between modules. The arrow direction indicates which module is the source on the information. This diagram has inputs and outputs at the bottom interfacing with the hardware using software drivers. Each process block uses the input information to compute or schedule outputs.
Set Steppor Motor Outputs
Sense Switch Inputs
Time Delay
Compute Controls
System Management Time Event
Step EventDir, Mode
CPU Crystal Oscllator
IO to Stepper Motor
IO from Switches
Switch State
Dir Mode Delay
Poll Command
Update
Delay Period
Figure 2. Data flow diagram for stepper motor control
Control FLow Diagram
The data flow diagram does not describe what the process does or how the input data is operated on. (See Chapter 2 Step 2.) A control flow diagram is used to describe the sequence of operations that implements a process. The control flow diagrams shown in Figure 3 through Figure 5 illustrate how they can be constructed with hierarchical levels of detail. Figure 3 is the top-level flow diagram that represents the entire process. Figure 4 and Figure 5 provide greater details of the processes that step the motor and update the operating parameters. Additional details can be modeled for the “update table pointer” process shown in Figure 4. Using the hierarchical flow diagrams reduces complexity and eliminates potential confusion from intricate figures. The features of the process are explained in a top-down fashion. Both the data flow diagram and the control flow diagram are needed to completely capture the organization of the entire process.
Initialize system
Delay
Step Motor
Update parameters
Figure 3. Software flow diagram for stepper motor control
Figure 4. Software flow diagram for stepper motor function
Update parameters
Input switch state
BUTT 2
Td - TD Mode = FS Dir = CW
Yes (^) No Td - TD Mode = HS Dir = CCW
Continue
Figure 5. Software flow diagram for update parameters function
Sequence Diagram
A Sequence diagram depicts the sequence of actions that occur in a system. The invocation of methods in each object, and the order in which the invocation occurs is captured in a Sequence diagram. This makes the Sequence diagram a very useful tool to easily represent the dynamic behavior of a system. A Sequence diagram is two-dimensional in nature. On the horizontal axis, it shows the life of the object that it represents, while on the vertical axis, it shows the sequence of the creation or invocation of these objects. Because it uses class name and object name references, the Sequence diagram is very useful in elaborating and detailing the dynamic design and the sequence and origin of invocation of objects. Hence, the Sequence diagram is one of the most widely used dynamic diagrams in UML.
Defining a Sequence diagram
A sequence diagram is made up of objects and messages. Objects are represented exactly how they have been represented in all UML diagrams—as rectangles with the underlined class name within the rectangle. A skeleton sequence diagram is shown in Figure 6.
