FormatCode Documentation |
|
Documentation is program listings or technical manuals describing the operation and use of FormatCode Code Formatters. In general terms, documentation is any communicable material (such as text, video, audio, etc., or combinations thereof) used to explain some attributes of an object, system or procedure. It is often used to mean engineering or software documentation, which is usually paper books or computer readable files (such as HTML pages) that describe the structure and components, or on the other hand, operation, of a system/product. By engineers, perhaps among software engineers in particular, documentation is often referred to as the "boring side" of engineering, or considered a necessary evil. This is largely unavoidable since most engineers prefer building things to documenting them, and being implicit experts in what they have built, they may have little motivation in documenting their creations so that others may understand them. Common types of computer hardware/software documentation include online help, FAQs, HowTos, and user guides. The term RTFM is often used in regard to such documentation, especially to computer hardware and software user guides. A common type of software document frequently written by software engineers in the simulation industry is the SDF (software documentation folder). While developing the software for a simulator, which can range from embedded avionics devices to 3D terrain databases to full motion control systems, the engineer keeps a notebook detailing the development lifecycle of the project. The notebook can contain a requirements section, an interface section detailing the communication interface of the software, a notes section to detail the proof of concept attempts to track what worked or didn't work in solving certain problems, and a testing section to detail how the software will be tested to prove conformance to the requirements of the contract. The end result is a detailed description of how the software is designed, how to build and install the software on the target device, and any known weaknesses in the design of the software. This document will allow future developers and maintainers of the trainer to come up to speed on the software design in as short a time as possible and have a documented reference when modifying code or searching for bugs. Any material that aids users to overcome problems, make decisions and perform tasks more efficiently. Typical documentation includes printed user guides, reference manuals and online help. 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. 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 divise 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. |
