Where tests have a significant and unpopular position in the workflow of most developers, some of us skip that part because we have no time to do it, and documentation is even less popular. “Documentation is a waste of time”; “Most documentation is already outdated before it is written”;
“Once written, we will never look at it again”. To mention a few excuses not to write any documentation. And this outlines the problem.

As a contractor, I have worked for various companies writing their own code, trying to build a stable product for their customers. Some are more successful than others. One project is bigger and more complex than the other. All of them are beautiful projects, serving the purpose they were built. But they had one major issue in common, they needed to be documented.

I will always read the documentation when jumping into a new project or using a new library, don’t you? Many developers complain about the lack of documentation for open-source projects or poor documentation. So we do need documentation. But only if the code is not ours. And we can agree that after a while of working on this significant project, you will only be able to remember some details of a project. And when you have been working on another project, you might feel like you are new to an old project. Jumping on the rolling train is a reality for people like me. But also for your future teammates.

So we need documentation as we need tests because it’s one of the tools that will help us understand the project. Documentation allows you to communicate about your project with people who cannot read the code (yet). But documentation is also another level of abstraction on the technical specification of your project, being your code in the purest format. Yes, your code is the most detailed format to write documentation. It’s even so detailed that we can execute it with a computer. So we write down every application detail but in the wrong format. A format that is not understandable by unspecialized humans.

Facing the problems I mentioned about time, redundancy of information, and the interest of developers writing documentation, it’s good to take a look at how to improve that part. There have been many projects about writing human-understandable code (Natural language programming). But somehow, NLP fails, natural languages are too ambiguous, and computers have difficulty understanding context. They resulted in languages like COBOL, Apple script, and ClearTalk. Complicated to process for computers and humans because of their limited syntax, needing to be more natural. We all (at least I do) like the programming language we use daily. Switching languages doesn’t feel comfortable as well. In my opinion, the secret is the other way around. Going from a non-natural language to a more natural one. This system will not be perfect, but humans can understand imperfect language, especially when it’s their own native language.

For me, this opens a new opportunity. Building a highly complex system which I like to work on, in my own comfortable programming language, producing documentation. This solution solves several issues because we are automating things we do not need to spend much time writing documents. We can spend our time writing code that we like. The documentation is updated when the code changes so that it will be accurate. And because of this, people will be more tempted to read and use the documentation while working on a system. And as the documentation is generated it does not matter that it’s redundant. I’m fully aware of the complexity of this whole project, and I think it’s impossible to remove the need for handwritten docs entirely. But at least we can try to approach the goal. And start automating the parts we can automate.

So next time you start drawing your new architecture, consider integrating this into your code. Use attributes, annotations, and add other metadata to your code to mark the key components of your code. Use the reflection tools like phpstan, deeptrac, psalm, phpDocumentor, and many more to extract information from your code and validate the structure. Define a set of definitions you use in our code and during meetings with your business and customers. And bring that together in a set of wonderful scripts that will help you to create the most admirable documentation set you have ever had. Meanwhile, I will keep dreaming of a world where documentation goes hand in hand with our code.

I’m @jaapio, the maintainer of phpDocumentor, striving to create the best possible documentation framework for the PHP community. That will help us to make a significant step forward in the world of “Living Documentation”. Thanks to Cyrille Martraire for being an incredible inspiration to find a new path for improving phpDocumentor.