A lot of times, people who write code can wonder why so many insist on documenting each step of the progress. Documentation can have a different importance for the unique roles of those interacting with the product, and can make or break the successful completion of functioning code.
- For the Developer, this provides a tangible roadmap to return to for reference. This is invaluable in testing, as end stages can be tweaking small sections of the same section of code.
- For the Reviewer (QC), this will help determine whether or not the code is functioning appropriately. An error could be overlooked if the input just happens to lead to a perceived expected output only by accident or coincidence.
- For the Maintainer, this helps monitor functions for compatibility and continued use. As operating systems change, technicians working to keep an application functioning will have a better idea of what areas need focus.
- For the User, this elaboration can help with understanding the functions embedded in the code. People with a basic understanding of code can better follow more intricate layers when they are following a labeled path.
- For the Fixer, this will reduce having to troubleshoot fully blind, should something wind up causing issues down the line. As this person may be someone other than the one who wrote the code, documentation will inform this person how the code “should” function in every aspect, narrowing down the causes of potential defects.
When developing apps for your own, individual use, it can be tempting to assume that each of the above roles will be only performed by you. Even should this be true, documentation can still help with long-term use. The mindset the coder was in while writing the code will not be fresh when revisiting it, later.
During the creation of an application, there are so many moving pieces that it can be a task to arrange the information to be used as a reference. When in doubt, it’s almost always preferred that details are better included than excluded. When writing the actual material, it is suggested:
- Base everything around the code. Reviewers will better be able to simultaneously follow the coding and the material when they are both structured similar.
- Make all formatting, tenses, and tones consistent. Documentation is easier to understand when the language flows smooth.
- Use plain English as much as possible.Jargon should only be used when unavoidable, Not everyone uses technical terminology consistently, and this could lead to unnecessary confusion.
- Describe. Include examples. Avoid introductory how-to instructions that are needed to be known outside of this source, opting to link to such basics.
- Be accurate, and revise updates as needed. Should there be a difference between the app and the material, the reader may not know which is correct.
- User– Usually book-style, this explains the best way to use the features of the app.
- Requirements – Lists the necessary components for the use of the app.
- Architecture– Details the build design, often used for online marketing and search engine optimization.
- Technical – Describes the code as well as interfaces and technical aspects of the app.
- Source Code – The pure text of the code for the app, often used for review during any alterations.
Users and technicians who did not write the code will be able to understand the code on a deeper level if they know the thought process of the development of it. Even embedding comments within the code can make it easier for someone to locate a particular section focused on the need.
An easy way to do such:
// First Perform Function 123
code to perform function 123
// Follow with Function 456
code to perform function 456
This example of internal documentation is excellent for quick reference. It allows the reviewer to see added notes in tandem with the functions. However, for simplicity sake, there can only be a limited limited amount of information included to keep from flooding the text. This creates a need for external documentation.
For the big picture, many wonder what documentation should be produced, and struggle with trying to determine what information is vital and what is frivolous. At its most basic, it needs to explain how the app works, and how to best be used. In generic outlining, the most common categories of documentation are:
Reference guides need to be information-focused. It helps to draft them to allow for easy expansion and/or alteration as tech upgrades may require such. A consistent formatting structure can facilitate this in later revisions, as well as assist reviewers with navigation of the documents.
Some of the most common, and frustrating, issues a coder can create is “Spaghetti Code.” Issues along those lines are preventable, or can otherwise be more easily fixed when coding has been adequately documented. It’s certainly worth the time given all that it provides.