Proper documentation of software systems is a requirement for successful and timely development of software, as well as for its subsequent usability. On the other hand, the documentation investment has to reflect the needs: it should be as succinct and as painless for developers to write as possible while maximizing the benefits to users and other developers who must work with the code.
At the DAO, current software developments, e.g., PSAS 2.1 and beyond, are being written in Fortran90. Due to the relatively recent arrival of Fortran90 there are few software development tools available. There is a clear need for sufficient code documentation at the DAO to keep co-developers informed on a day-to-day basis, and it will be helpful for future maintenance and use of the production code. Therefore the we have developed ProTeX and a set of documenting conventions to satisfy the needs of the DAO PSAS 2.1 development. The ProTeX conventions are fundamentally a superset of the DAO ``software standard.''
The rationale for such a system is explained in section 2 through documentation examples from other software projects. The requirements of the DAO are then enumerated in section 3. Existing software documentation tools are analyzed in section 4, and their strengths, weaknesses, and applicability to the PSAS software development discussed. The proposed documenting guidelines and the ProTeX system are described in section 5. We conclude in section 5.3 with a discussion about possible extensions. The appendix A contains the technical reference manual for ProTeX.