We were lacking documentation while we develop themes or plugins for the Opencart but found PHPDoc which makes our documenting our PHP projects easily. A good programmer who takes responsibility for communicating with other programmers must support documentation. Whenever we write code we started thinking of 5Ws and write each for better documentation
5Ws for better documentation
What, when, where, how, and why should be answered while creating better documentation. We came up with the following ideas to list in our documentation. It is just our idea, yours can be totally different.
What: Power Statement
"What" will be a title, which includes Issues Titles, Steps title, new Features Title, functionality title, etc
When and Where: Description
"When and Where" will be included in the description. The description will include:
An excerpt that you can write
Tools/Websites/Template name/Plugin name
Include Ticket links
Github code links
Why: Codes and logic implemented
In the "Why" section we add codes and logic
How: Output Test/Reports/Metrics
In the "How" section we add output, test, reports, and metrics.
Example of the PHP project documentation
You can use multiple tags listed below which you can use in the comments Docblock:
After we ran this, we got the docs folder in the project folder.
After this go to the docs folder where you see multiple folders like below then open index.html
When you open index.html in the browser you will see something like the below:
With these simple steps and adding comments in the code we are in the process of becoming good developers, you guys also can start making the documentation so easy for developers. Hope you will start documenting your project easily, let us know if you have any questions or suggestions, please subscribe to our YouTube Channel for Opencart video tutorials. You can also find us on Twitter and Facebook. Enjoy!
I would argue generating static documentation is very old school, like mainframe old school 1950’s think.
We now have everything we need to generate documentation on demand via PHP reflection classes.
I also find the quality of the generated documentation is not up to the latest responsive mobile friendly standards. Plus it takes time to generate the documentation, and we tend not to do it, and even if we do regenerate it, it does not reflect the changes to the code we just added, since we did not regenerate it since the last time we saved our changes.
So I solved all these problems with PHPFUI/InstaDoc. Install it via Packagist and add it to your project in about 2 minutes. Complete, always up to date and hyperlinked documentation!
