Documentation and Standardization of Code

Languages

Peoples with different experience, knowledge and skill need to be at the same page when they are working towrds same goal. To make sure everyone means same thing about a thing, implementing a standard communication is important. Mistakes caused by miscommunication can drain resources fast and could waste useful time.

Language exist so we have same meaning when we say about something–at least it suppose to. We agree that this words means something; codified in a dictionary. We treat dictionary as a reference when we don’t know what a words means. Language can be rigid and fluid. Maybe for critical operation we need to follow a rigid protocol whereas for brainstorming and finding new ideas, we want to utilize more fluid language; rarely written in dictionary.

We need to find balance between this rigid and creative approach so that we don’t feel pressurized by protocol but not too unconstrained that we lost certainty in our language.

Dictionary and Documentation

Now we already construct basic analogies, now it is time for the message. We need to construct dictionary. Everyone could contribute to dictionary to add more words. But there are few special people that curate any soon-to-be-added word so dictionary only have important and relevant and reject any potential double entry.

Dictionary for a project is a documentation where any developer or any involved entities could refer so anyone participating could understang what s/he says. The curator is the maintainer of a project. Documentation need to be rigid because it act as reference.

Complete is the purpose of documentation. We could start at basic knowledge that everyone has and climb up to more unknown terms that only few people knows. These few people is the one should add more entries to documentation.

As projects developed, many people will have different knowledge about the project. Many people have knowledge intersect with each other but there are also who don’t have intersect at all. This is where documentation comes in. When there is a person who want to work in certain areas that they don’t have prior experience, s/he could consult the documentation.

This act provide two advatange for team, a test for how well a case or feature is documented and decreasing hassle for people – let’s say a developer – who work for that case or feature. Decreasing hassle is important part of developer work because it lets developer focus for work instead of explaining stuff that can be explained by reading a documentation that could accessed anytime.

Standardization and Documentation

So we know the importance of good documentation, now we move to how we write a good documentation? In software development, there are two types of documentation, creators and users. The creators documentation should be superset of users documentation because not only it contains how to use and what to expect but also the logic behind how to return the expected result. There is no standard how we write a documentation but there is a baseline that we should follow.

Complete and clear; a documentation should contain enough knowledge so one could reconstruct the case based on documentation in an unambiguous way. In creators documentation, one should be able to reconstruct the case or feature based on documentation and in users documentation, one should be able to use it and have the same result as documentation shows.

Reconstruct a case need a standardization because there is many way to do one thing. If every one have their own way to create something, the main code would be messed although the server or compiler still understand it and execute well. Having a flexible, optimised, one way to do certain task could help cut development time because developers already familiar with it and does not need extra time to understand it. Such way need to be preserved as a good practice should not be sacred.

Code Inheritenace and Scaling Argument

Combining both documentation and standardization will yield a good code inheritence. This also sloping learning curve for new user or developer. S/he could catch up knowledge with their peers faster and follow team’s pace faster. Again, additional team member could cut development time only when s/he well aligned with other team members. Lost and confused team members will not change or worse increase development time. Cutting development time while delivering a good work are goal of every development team.

There is one more argument why we need standardization and documentation. Usually, the worth of tech companies – especially the one who uses internet as their main product – measure itself using growth. How fast a companies grow is a popular start up parameter. We believe every company want to seize every potential market share. In process of doing so, developer(s) team need to met demand pumped by its companies growth.

In order to seize every opportunity, developer team need faster and sustainable development cycle. Every opportunity requires more features. Without standardization, every feature created by different developer could end up so different that any other developer unable to read their peer code. Documentation makes sure no knowledge left unrecorded. Documentation could avoid double creation of a same function or class. Recording and storing a feature or case in a documentation helps other developer learn about a feature or a case without s/he participate in that feature or case. It also helps when a team want to extend a feature without a team who created it.

Documentation makes sure everyone involved in a project get in the sampe page. Other problem that developer team face is high turn over. A developer could get in and spend only three month helping develop a project and left. Documentation and standardization makes sure s/he could get in shapes fast so it maximizes his/her contribution to project in such short time span.

Last argument why documentation and standardization is important when scaling is there will be a time when knowing everything about a project is practically impossible. Sometimes it is enough to know where you could find the answer and implement it.