Documentation for your application is important because it helps to provide important information and visual representations of the code and other parts of the application. This will make it easier to do handoffs with other developers and engineers as well as perform checks for troubleshooting, updates or maintenance.
Good documentation is important. This could range from documenting the code and its functions internally to providing external documentation that provides added context about what was built. There is also user documentation that tells the user how to access and use the application.
The different types of documentation we will discuss in this post will pertain more to helping the developer and technical users who will need to perform work, updates or maintenance on the application. These types of documentation focus on the team documenting what they are building, usually by adding information in the code explaining what certain functions do or drawing up the necessary diagrams that outline certain flows and functions of the software and system.
Entity Relationship Diagram (ERD)
To understand what an ERD is, we first need to define what a database (DB) is. In technology, if you’ve accessed a website or application, chances are it will have a database tied to it. A database is a way to collect and organize information to be stored. By taking certain actions on that website or application, you will be able to create, update, edit or delete info inside of the database.
ERDs are diagrams which show the relationship of the many elements found within a database. Evidently, engineers use ERDs to understand how all of the data found inside of a database are related to each other. The parts of an ERD consists of the following components:
- Entity: Tracking an object. It could be a place, person or thing. They are the rows of a table on a database. In the ERD, each entity represents a table in a database.
- Attributes: Consists of traits or properties. They are the columns on a database table.
- Keys: Are either primary or foreign. Primary keys identify every record in a table uniquely. For example. An ID# or Username is a good primary key because it is consistent, unique and never changes. A foreign key, on the other hand, is the same as the primary key but it is located in another place. The same foreign key can be used in multiple tables for example.
- Relationships: Are the lines that connect the entities and their attributes together to show their connections.
- Cardinality: Shows the minimum and maximum relationship between entities and their attributes. Relationships can be one-to-one, many-to-many, one-to-many or many-to-one. There are also situations to use zero.
ERD Example Template from LucidChart
Application Programming Interface Documentation
Application Programming Interface (API) in layman’s terms can be considered an interface or bridge that connects a software to other external or internal software components. It’s a way to organize and reuse code components. For example, if you have a store on your web application and want to be able to process payments, you will probably link to an external API that will connect you to a payment processor in order to process payments through your web application. So, an API deals with the interactions with software components.
Having API documentation for software tells developers and engineers how they can access, connect or integrate with that API and what their requests and responses will be in order to send and receive information. It’s the part of a server that performs these functions. The documentation will outline things like resources, endpoints, request and response examples, parameters, authentication, status and error codes, code samples, SDKs and more.
A few popular API tools include RAML, Swagger, Postman, SoapUI and GraphQL.
Server Documentation
To manage network resources a computer or program uses a server. If you built a software application, you will most likely deploy it to a server. That way it can be accessed and used. Server documentation tells a developer or engineer how to configure and connect to a server. It also provides useful information for maintenance, troubleshooting and debugging problems on the server. Server information may include it’s IP address, URL, stack, configurations, dependencies, software, user credentials for accessing the server either via FTP or SSH and more.
Deployment Process Documentation
Deployment process documentation lists out the steps and instructions for deploying code on a server. Usually, as part of the development process, it would be located in the README.md file of the application’s Git repository. Therefore, some of the information you may find in a deployment process document includes requirements for the server, parameters, permissions, how to run the server and more.
At Grata, we use GitHub and LucidChart heavily for much of our documentation. Nevertheless, that is why we have chosen them as the source of our examples in this post. However, you can draw diagrams for you application with many tools available online. Simply do a search online for the type of diagram you want to draw such as “Tools for creating UML diagrams.”
For additional learning, watch these LucidChart tutorials:
Ready to Build or Fix Your Application? Contact Us Today for Expert Solutions!