In the past years, PHP web development has come a long way. In earlier years, PHP’s open structure (giving developers the freedom to structure their code as they wish) was rendering projects unmanageable over time. Which is still a struggle for most developers, even now.
Luckily, the open source community found new ways to overcome some of these issues. Defining standards for writing code, auto loading, using namespaces and solutions for working tighter with Internet standards. It wouldn’t have come this far without an open source community, and a wide variety of developers willing to publish their code. But why is this community able to produce high value code? And what can we learn from it, instead of only using it? I soon found, that using the same strategy for documentation, is a first step towards this goal.
Why are huge commercial companies like Google, taking it a step further by opening up internal projects? We know that some technologies will never be shared. Because these technologies make Google what they are, the best in their field.
Partly, we can believe Google marketing on their open source strategy: “Google believes that open source is good for everyone. By being open and freely available, it enables and encourages collaboration and the development of technology, solving real world problems.”
But is there more to gain?
In the process of making your project(s) available and readable for a broader public, you will soon find that this process alone can help boost code quality. Simply because you need to tell a story around it, making it readable and understandable for a broader public. Weak spots you find, or even already know of, are required to be marked and eventually be solved.
Giving a development team this task, is something that should be mandatory, but can be a real struggle (especially within smaller companies). The first step is to start (re)writing your documentation with a new mind set. Automatic generated documentation can be helpful, but only cover end results. Good documentation examples can be found at open source projects (https://laravel.com/docs/5.4).
Some things I’ve learned from open source development teams:
- Keep your documentation open during development at all times. Start small, and extend on the go.
- Use markdown files to enable collaboration.
- If you’re in a country that doesn’t have English as a native language: English is at this moment, what API’s are for data.
- Add standards and guidelines.
- Pitch your software in an introduction even if this part will never be read outside of your company. Really, you should.
- Explain a clean installation process, even if you rarely use this. You will benefit from this, if you ever need to migrate. If this process is to complex, find ways to make it easier.
- Start testing your environment requirements. What software versions are required to run on your server. You can test this with virtual machines. You can also define these requirements in Composer for testing new server environments.
- Explain your architecture. This will also give you insight in all types of elements available (Controllers / Methods / Services / Crons / … ).
- Explain those elements. What do they do? When should they be used and why? Be extensive. Have you found parts that really doesn’t fit your architecture? Mark them to be reviewed, the probably need improvements or sometimes even a rewrite.
- Find all external packages that weren’t developed by your own team. Only the lines of code that are using these packages, should be in your own repository. See this packages as risk factors that you need to address. Manage them outside your code, with (for example) Composer.
- The same goes for all external resources, like 3rd party API’s.
Improving your documentation, should be part of your routine.