At New Target, we require our software developers to comment on and document all of their code. We ask this of our team because it’s a best practice and a benefit to our customers that serves them in three principal ways.
– Documentation helps the end-user of the software by helping the reader understand how a code works. If you are savvy in the language, you can figure out things on your own. If you aren’t, then you are lost.
– It helps other developers on the team stay on the same page with the original author thus avoiding confusion and saving time and money.
– It helps the coder quickly recollect their original thinking thus saving time and money if they have to work on the code at a later date.
Any time saved in the process will benefit the customer’s bottom line.
Web developers write computer code. Essentially, it’s a language that they are expert in. What we are asking in comments and documentation is that they translate that foreign language into English for the benefit of a wide range of readers. Documentation records what is being written in code and why.
Good Documentation Helps Users
Documentation helps the reader understand how a code works. Documentation intended for users usually consists of practical use or the “how-to.” The rule of thumb when creating documentation for general users is that it should be clear cut, using common words instead of industry jargon.
Documentation Helps Other Developers
Each developer will have their own coding style. But, when it comes to working in a team, they will often have to share code with other developers. So, it is essential to have a consensus on a standard to keep everyone on the same page. A properly written documentation would be the reference the team needs.
But unlike end-user documentation, this documentation typically describes technical procedures like the code-naming convention, showing how particular pages should be constructed, and how the API works along with the code examples. Often, the documentation is written “inline” with the code (known as the comments) to describe what the code is doing.
When new members join your team later, this documentation could be a time-effective way to train them.
Documentation Helps the Coder
The funny thing about coding is that sometimes even the web developers themselves do not fully comprehend the code that they have written. This is particularly true in cases where the code has been left untouched for months or even years.
A sudden need to revisit the code would leave one wondering what was going on in their mind when they wrote it.
By documenting the code, the web developer will be able to get to the bottom of it quickly and without frustration, saving a lot of time.
Good Documentation Rules
1. It’s always better to start from the very beginning regardless of the users’ proficiency level.
2. In adding documentation that goes inline with the code, it’s always a good idea to describe each function, the variables, as well as the value returned by the function.
3. Graphical elements speak better than text. These media are useful, particularly if you build software with a graphical interface. You can add guiding elements like arrows, circles, or anything that may help users to figure out where to go to accomplish the steps, without guesswork.
4. Wrapping a few things in the documentation within bulleted lists and tables makes longer content easier to scan and read for users. As does adding a table of contents and splitting the documentation in easily digestible sections.
5. Revising the documentation whenever there are significant changes to the product, software, or library is critical.
Where Documentation Is Usually Focused
Documentation is usually focused on the following components that comprise an application:
– Server environments
– Business rules
– Application installation
– Code deployment
Website Server Environments
Detailed documentation about an application and its environments is always a must. This information will help with setting up new environments for your application and it should present the location and function of the systems that run your services. Things that should be specified here are the application name/version (Drupal 9 or WordPress 5 for example), server name, IP, code directory, URL to the application, operating system, user account information, and a point of contact.
Having a business rules document is extremely helpful for developers who need to learn how and why the web application works the way it does. In addition to business rules, a Help document, FAQs, or User Guide can help highlight the main points of an application for a web developer who needs context for the application they are supporting.
If the application has a database, it’s helpful to know the type of web database, the server information, the version, and if possible, the data model diagram. It’s good to document what server the application sends or grabs files from, user account information, and whether any SSL certificates are needed.
The troubleshooting documentation helps when running into production issues. Most technical issues should have error codes that help with troubleshooting. In this document, there should also be included an FAQ section to deal with general or usual problems (such as configuration issues). The errors should be documented split by type of error, module where it comes from, and level of error.
Installation and configuration documents are useful for when developers need to set up new or additional application environments. If possible, the steps should be detailed and easy to follow and can include screenshots if necessary. Anyone should be able to follow the steps and successfully install an application. Having the steps identified will help the installer prevent problems because of missing parts of an application. Details such as necessary software, libraries, and application server versions, can be included to ensure the environment will be compatible and set up as intended.
The code documentation is the backbone of every web application. Code documentation can be split in multiple parts. The first one, the most helpful for programmers is the comment blocks. These will be found through every file explaining classes, methods, parameters, and possible errors. Then comes the specific file documentation. These are usually generated through a third-party script which will parse a file and, based on the comment blocks, will create an explicit PDF.
Afterward, there should be information regarding the code repository, where the file updates are found, and where they need to be moved. In addition, there should be step-by-step instructions on how to create an application package or a build to be deployed.
Writing documentation takes time. It needs to be understandable and updatable. If done up-front, documentation will definitely save time and money in the long run and serve our customers well.