Effective Documentation Practices for Programmers
Written on
Chapter 1: Understanding the Importance of Documentation
Programming transcends mere code writing; it encompasses a range of essential tasks including documentation, analysis, testing, and reporting. In this section, I will outline my approach to documenting programs effectively.
Section 1.1: Requirements Catalog
Every program begins with a detailed catalog of requirements. This document, akin to a wish list for Santa Claus, is crafted collaboratively with future users to ensure clarity on essential features. However, gathering these requirements can often lead to challenges, especially when dealing with clients who lack IT expertise.
Section 1.2: Acceptance Checklist
An acceptance checklist is vital for program handover. When the checklist is satisfactorily completed and the program is ready for deployment, the client must fulfill the final payment. Depending on the project's nature, it's also important to document test cases here. Our IDE includes a test generator that can automatically validate whether the final product aligns with the original specifications after any modifications.
Section 1.3: Integrated Database Management
We utilize an integrated database within our IDE, which outlines data fields and visually represents database relationships. This database is automatically generated and incorporated into the program. If any changes occur during or after development, the existing data is seamlessly restructured, which is a highly beneficial feature.
Chapter 2: Best Practices for Code Comments and Documentation
Incorporating comments directly into the code is crucial for future developers, including myself. After completing numerous projects, I've learned the significance of clear annotations, particularly in complex areas that may be challenging to understand later.
Section 2.1: Developer Documentation
While coding, I also maintain a brief developer documentation, which captures essential information for those who may work on the project afterward. Many program interfaces are standardized using a generator and an internal reference guide, which simplifies the documentation process for larger projects. Any subsequent changes to the program are also recorded here, even if they weren't initially documented in the analysis phase.
Section 2.2: User Documentation
Once the user interface is established, I focus on creating user documentation. This documentation serves as a help system and is compiled into a .chm file using a help editor. It's critical that both developer and user documentation are developed concurrently with the programming process.
Section 2.3: Website Documentation
Prospective buyers of standard software seek clear explanations of its functionalities. Therefore, it is essential to document the program's features in an accessible manner. To aid understanding, we produce videos that showcase the program while highlighting various less obvious features. These videos include narrated explanations, which the developer must carefully prepare.
In conclusion, it can be said that around 80% of what is considered "programming" time is dedicated to documentation tasks in a broad sense.