1310 1499 1190 1354 1139 1635 1422 1665 1362 1371 1327 1698 1264 1864 1829 1472 1662 1887 1494 1499 1516 1600 1826 1114 1954 1268 1759 1529 1863 1380 1011 1753 1231 1389 1868 1215 1644 1873 1833 1958 1294 1172 1893 1069 1566 1315 1863 1802 1106 1075 1747 1068 1060 1410 1446 1331 1213 1209 1583 1618 1282 1855 1177 1486 1476 1521 1919 1752 1802 1974 1797 1366 1536 1254 1897 1673 1826 1698 1731 1994 1145 1905 1001 1425 1904 1008 1760 1682 1198 1255 1180 1733 1307 1569 1164 1240 1164 1975 1978 Documentation of a project | PHPnews.io


Documentation of a project

Written by DragonBe's PHP blog / Original link on Feb. 20, 2019

In my previous post I described 10 steps we should take to improve security of web applications. In this article I'm going to describe the purpose of documenting a project and what information should be included.

Every successful project requires documentation to communicate a project goal and requirements to reach it.


Purpose of documentation

The reason documentation exists is to communicate in a clear, understandable language with all people involved. For web applications this documentation should describe the idea as a concept, steps needed to convert the idea into an application, what tools, applications and services are required in the proces of building the application, how the application is architected and who are the people involved.
Since documentation is never complete, a good structure is required to allow additions or corrections being made over time. I prefer to use a Wiki type of platform to write my documentation. A wiki has often a simplified markup language and allows for multiple editors to collaborate on the documentation. Wikipedia is a great example of using a wiki to write documentation. But other tools are equally good like Google Docs, Microsoft Sharepoint or Microsoft Word documents on a shared drive in your organisation.
For all our project we are using Phabricator as we can integrate references to tasks, commits, users and a whole lot more features in our documentation wiki, making it a true source of reference. With Phabricator we're able to create global knowledge in our team and in our whole organisation.
Example screens of Phabricator
Example screens of Phabricator

Structuring documentation

As mentioned earlier, documentation changes over time for a lot of reasons. Here are a few common reasons why I needed to change or add documentation:
To prepare your documentation for these and other changes, a documentation structure is required. What works for me and the people I work with is a structure based on "expanding knowledge". This is a structure that allows your documentation to grow, without becoming a single massive document.
At the start of every project I'm also using Phabricator's feature to create a "space", "team", "project" and "tag". Let me first explain what they mean.
The combination of spaces, teams, projects and tags with the documentation architecture described above gives me and the teams I work with clarity and insights about what needs to be done and what goals are to be reached.

Security aspect

As you're defining the components needed to work on your web application, don't forget to include security in your documentation! Most projects I worked on have been approached from a functional perspective where features and functionality are well documented, the architecture defined in terms of hardware and software requirements and who's doing what.
What I define as "security" documentation can be listed as the following:

Automation is key

Setting up environments with all required bells and whistles is a repetitive task that should be automated. It allows you to set up systems faster, but allows you to make improvements over time. This results in more stable and better protected systems. It also removes the fear that a step is skipped or a configuration setting forgotten.
Automation Tools
Automation tools to configure and provision infrastructure as code


GIT is not an automation tool but is an essential part of the automation process. GIT is a version control system where mostly developers keep their application code. But because GIT can be used for all text based (and limited binary) tracking of changes, we can also use it to store the automation artefacts in it.


A continuous integration (CI) and continuous deployment (CD) platform is not essential but highly recommended for the purpose of automation. My personal favourite is Jenkins CI, but there are many alternatives you can install on-prem or are being provided as a SaaS. Just search for "CI/CD Tool" in a search engine of choice you'll find plenty of solutions. NOTE: All automation tools mentioned below can also be triggered by manual commands on the command line.


HashCorp Terraform is a great tool to treat infrastructure as code. It allows you to quickly create your VM instances by using blueprints. Especially for Amazon Web Services, Azure or Google Cloud Platform cloud services it works really well. If you're using VMWare vSphere or Docker Containers, Terraform can be a true help. A full list of supported infrastructure can be found at www.terraform.io/docs/providers/index.html.


RedHat Ansible is a provisioning tool that aims at automating the installation and configuration of tools or services on your platform without the usage of agents. This means fast, repeatable setup of one, a group or all instances you have created.


HashiCorp Vagrant is an environment deployment tool to create virtual environments using Virtualbox or VMWare on a local system. It's great for creating local development environments and works great with RedHat Ansible to provision these virtualised platforms.


Docker containers are small, computational units of software, packaged as a platform with OS, network and application, that run everywhere the same way. Because there's no virtualisation layer between your application and your OS, applications run faster and require less resources. Even though Docker containers are great for development of micro-services, we now see more and more containers being deployed in production.


Kubernetes is an open source container orchestration technology that allows you to manage, scale and deploy containers with ease. If you're already using Docker containers, managing them with Kubernetes is highly advisable.

Next steps

Now that we have defined how we should structure our documentation, what aspects we need to focus on to make our application secure by design and how automation can help us ensuring that we have repeatable setup, provisioning and configuration of our infrastructure as code, we should get started applying what we have seen so far onto a real project.
In my next article I will document a web application project and provide examples how this would look like with the suggestions described in this article. Hope to see you next time.

googleblog calevans challenge dragonbe

« Building a modern app using Nest.js, MongoDB and Vue.js - New in Symfony 4.3: Form improvements »