How Much Code-Level Documentation a SaaS Team Needs

Source code documentation is an important tool to optimize the workflow of development teams and improve the communication efficiency between departments. Golden Section advocates for a source code documentation policy as a part of your development Standard Operating Procedure. This will allow your team to keep track of everything happening in your development projects and to easily see exactly what has changed at the code level.

The goal: Generate a code level documentation policy to explain code logic and track modifications to source code and to help resolve conflicts when merging updates.

Steps

1. Use the PDCA methodology described in Play: Quality Management Systems and the template provided to create a source code documentation policy.
2. Considerations:
   • A source code document is a technical section that explains how the code works. The aspects of the code that have the greatest potential to confuse should be covered. The main users of the source code documents are software engineers.
   • Try to keep the document simple by making short sections for each element and supporting them with brief descriptions. Source code documents may include but are not limited to the following details:
     • HTML generation framework and other frameworks applied
     • Type of data binding
     • Design pattern with examples (e.g. model-view-controller)
     • Security measures
     • Other patterns and principles
   • Golden Section recommends using GitHub for Source Code Management. Besides version control, GitHub can also help track project progress by issues, and its social feature will help with communication in teams. Below are some GitHub best practices to follow:
     • Before you push your change, in the Summary field of the comment, type a short, meaningful comment message including two parts:
       • Classification of change (category list will be needed for developers);
       • A brief and clear summary of the change (1-2 sentences).
     • Additionally, add some more details / information in Description if necessary.
     • We also recommend the developer team maintain README files and Wiki pages in each project to help the whole team stay on the same page.
     • Source codes might be shared with third parties, so it is indispensable to add a header to each source code with notice that explicitly states the code is the company's intellectual property. In the header, it is also necessary to elaborate on the purpose of this section of code.
     • We suggest equipping a detailed source code policy for various languages and usage. Make it clean and readable for internal team/clients.