Development Principle 3: How to create high quality project documentation?

High-Quality Project documentation is difficult to create but necessary for almost any project. It may seem redundant to take note of things that you already know or can easily set up, but utilizing documentation also assists with keeping the goals of your project clear and improving the overall efficiency of your project itself. 

Consider this example: We received an email a month ago from a client who had built a web app and data import system for them a year before. They needed to know why the import system was failing and how they could fix it.

We found no documentation about the application when we downloaded the code from our repository. There was a solution, but it took a while to find the right one. This example illustrates the clear need for documentation, particularly in the incidence of application or hardware failures.

In another example, Let’s Nurture needed one of its new developers to jump in on a project that was not fully developed using the platform they were familiar with. They were also still learning about Let’s Nurture’s procedures and workflows, which takes some time. We had the documentation for this project in place so it was easy to walk the developer through some of the major points and then let them go through the project document. This allowed them to set up the code and get it coded. Documentation is the key to making the entire process run smoothly.

We have been growing at an amazing rate at Let’s Nurture. It is crucial to bring a new or seasoned team member onto a project. We have a lot of programming languages and platforms we use to build solutions. We create a project overview at each root of all our code repositories. Here are a few tips your team can utilize when developing your own projects.

Start at Ground Zero

The documentation assumes the developer is unfamiliar with the code. The documentation assumes the developer is unfamiliar with the purpose of the project. By providing a high-level overview of the project, your documentation gives you numerous benefits. Of course, it’s important to briefly explain the project. A simple explanation such as “This project is an API portal that connects those who have work needs and those who want them to perform them” will put the developer in a good mindset and give them the confidence to ask important questions. If there are related projects, we will link them for your convenience.

We also discuss the platform, tools and any plugins that the developer will need to use for the project. It’s frustrating to have a project fail because you forgot to install third-party libraries that you didn’t know you needed. 

This makes it easier to manage all the information in one place: the project overview. The project overview also outlines where it is located for development, test, and production environments. When you are launching a new feature or bug fix, it is helpful to look at an existing application.

Soup to Nuts: Launch and Build

You cannot consider yourself “up-and-running” until you have pulled the source code and made the project functional in your development environment. The project document describes the steps required to get the project running, from “git clone to CTRL+F5 built”.

To make this process even easier, we’ve been working to move to Vagrant. If this is not possible, we will walk you through the basics of restoring the database and running any front-end dependency installations and environment configurations. Once this is complete, you’re ready to launch your project.

Deployment

Every project deployment is different. While there may be some common tools and methods for deployment, there are also configuration settings, platforms and other details that make each project unique.

The test environment could be a small web server that we use to make changes via FTP (File Transfer Protocol), while the production environment is a continuous integration platform. We outline the steps required to deploy the project to each environment.

Notes and Gotchas

We add special development notes (or “gotchas”) to every project. These are important for pointing out minor peculiarities in your code that may not be common among other projects. 

You might find that some resources are only required once. Because certain IDs are unique, you may have to modify the configuration settings manually. This helps developers save time and shortens the development time needed for your project.

Now, we’ll briefly describe the Github process for creating, reviewing and merging new features.

A lovely Welcome Page

Our project documentation pages are created using markdown. Once completed, they are saved as a README.md. Most (if not all) online source control systems will display this page in simple HTML format on their code repository home page.

This allows us to point developers to the code repository and allow them to get started. This approach to project documentation can be very effective if done correctly. It allows developers to quickly get up to speed without much hassle and with very little (if any) help. The real work begins once that is done.