Documenting software is one of the most crucial, but often most neglected, parts of the development process. Documenting your variables, functions, and entire programs is absolutely necessary if you are to succeed as a coder. Various sources will tell you to dedicate at least 10% of your development time to documentation. That is reasonable advice, and should be adopted when you are planning the development of any program or website.
After we cover some best practices for documentation, we will cover the general process for documentation (listed below). Each of these will be covered in detail in the following sections.
Pseudocode
Convert pseudocode to comments
Update comments as program changes
Add summary/high-level instructions
Develop user documentation (API docs) and technical docs (for other coders and administrators)
The first step of documentation should take place before you write a single line of code. If your organization follows a “Waterfall” process, there will be several planning and “vision” documents that outline all the resources needed and plans for development. However, in the Agile project management process, teams produce far fewer documents before development starts. The product owner may create a document outlining user requirements and goals for the project, but most of the documentation will come during and after development.
What are these development documents used for?
The main reasons why people need the technical design document for their work:
Stakeholders require the reports.
Customers need to feel more secure and at ease using the program.
To keep track of everything on the project.
For Audit purposes.
As a training material for new people in the team.
Only the relevant information
Agile suggests that only the most necessary information should be documented. What is the need for documenting something everyone knows? Create a vision, if it helps you to get fundraising. Write only the customer documents your customers require. Document your decisions only if there are alternatives and you need a reminder of what was behind those decisions.
Wait before documenting
This is the best way to avoid the false information in your papers. Document late. Wait until the decision is implemented and there’s no going back until you actually put it on paper. The information is stabilized and reliable. You economize the cost, time and effort, spent on redoing your documents. Note: This only applies to high-level documents that explain your program to a user. You should document your code with comments/pseudocode before you write any code.
Be specific
Keep in mind, that every project has its own requirements and specifics. You cannot apply the document templates for one project while working with another one. Some fields might not even exist in a project whilst some important ones are missing.
In addition, the customers are different and what works with one is simply not enough for the other. Let the customers decide on the content and amount of your documentation. It will save you some extra work and nerves.
Keep it all in one place
Technical design documents have to be accessible and transparent. You need to have them available for anyone who might be in need for them. So as not to have a mess, keep all your papers in order and in one place. A real life-hack is to create your own Wiki or at least a separate folder in your GitHub repository that everyone can access.
For more info on Agile documentation can be found here.
Once the general requirements and goals have been documented (or at least discussed and agreed upon by the team), you should start by writing pseudocode. Starting with pseudocode will help you think through all the functionality of your program without getting distracted by the technical details of how you will implement it. The added bonus of creating good pseudocode for all the functions of your program is that pseudocode is easily converted into comments.
To review the steps of how and why to write pseudocode, visit the following link:
https://www.wikihow.com/Write-Pseudocode
A quick summary (halfway down the page) with examples: http://userpages.wittenberg.edu/bshelburne/Comp150/Algorithms.htm
A quick video description is here