Guidelines for embedded software documentation

• Authors: Nenad Marovac
• Venue: ACM SIGSOFT Software Engineering Notes
• Year: 1994

Embedded program documentation, i.e. documentation included in computer programs within program comments, typically does not follow any formal standards or conventions with regards to its contents and structure.Software development organizations do not enforce any standards covering the information content or format of the embedded documentation. At best they may encourage the use of some proprietary rules. It is very common in such organizations that individual programmers have their own individual documentation styles.This is unfortunate since embedded documentation, containing proper information and being properly structured, can greatly assist us in reading and understanding software programs and their individual components during the maintenance of these programs or reuse of their components. Furthermore, the use of embedded documentation can assist in functional decomposition and design of computer programs and in ensuring the consistency of interfaces within programs.The purpose of this document is to report on the schema we use at San Diego State University in software projects and to propose guidelines regarding documentation embedded in computer programs and related documents. We believe that these guidelines will help us to maintain conformity in software documentation in programs developed at SDSU in Software Engineering and MultiMedia Labs.Furthermore, we have developed tools that are based on the proposed embedded documentation and that are used in four areas:1. interactive functional decomposition and design of programs2. automatic incorporation of submitted software into reuse libraries3. conversion of developed software into hypertext like structures that are used to maintain all material related to a software project in a form suitable for inspection, browsing, and updating4. automatic generation of software documentation on demand