We have been working with Hubzilla software for awhile now as contributors and third-party developers. After awhile you get used to the concepts and where things are located in the codebase. But when you bring in new developers, there is a steep learning curve. And if you haven't worked on something in awhile, sometimes you need a reminder on how things work. So we wanted to create some comprehensive documentation specifically for developers.
Another goal of ours was to unify codebase documentation for the core and third-party addons, widgets, and themes. It will help developers see what is possible and give examples of code.
And on top of that, there are two other projects related to Hubzilla with compatible licenses: (streams) and Forte. They are similar enough where code from one project can be ported to another project. Although our documentation will focus on Hubzilla, we will also link to the (streams) and Forte code where it may be useful for developers.
For example, we created a page for the Admin Site Settings page in Hubzilla. The codebase & URL wiki contains information about the many files called to build that page, such as the modules, templates, and page description files. Plus we linked to the repositories so you can see the actual code.
https://development.guide/wiki/hubzilla/code/admin/site
Later we will expand it to include information about the database tables used, available hooks, and any related mods that alter the way this page works.
That last part is probably one of the most important aspects of this documentation. Since Hubzilla can be modified using addons, widgets, and themes, and has hooks that can override the core code, it is useful to see everything in one place.
That way we avoid conflicts and breaking changes. For example, if core developers are refactoring the code, if they know that certain addons or themes depend on that code to be a certain way, then the changes can be coordinated in such a way where there are no sudden surprises that something stops working. At least, that is the plan. And on the flip side, third-party developers can understand what can and can't be overridden in the core using hooks.
But, as you can guess, this is going to be a huge undertaking. To address that, we make it a wiki, which allows us to grant access to other developers and technical writers who want to contribute. We will also be adding to the documentation over time as we build more stuff. So, initially, a lot of the documentation will be related to what we are currently working on.
I am sure it will be rough around the edges and incomplete for awhile, but we have to start somewhere.
Another interesting aspect is the integration with the new project management system that we are rolling out. When looking at the documentation, there will be a section that has a list of related tasks. And the related tasks will link back to this documentation.
This is what we are building. I think it will make a big difference and help contributors collaborate on Hubzilla and related projects.
Another goal of ours was to unify codebase documentation for the core and third-party addons, widgets, and themes. It will help developers see what is possible and give examples of code.
And on top of that, there are two other projects related to Hubzilla with compatible licenses: (streams) and Forte. They are similar enough where code from one project can be ported to another project. Although our documentation will focus on Hubzilla, we will also link to the (streams) and Forte code where it may be useful for developers.
For example, we created a page for the Admin Site Settings page in Hubzilla. The codebase & URL wiki contains information about the many files called to build that page, such as the modules, templates, and page description files. Plus we linked to the repositories so you can see the actual code.
https://development.guide/wiki/hubzilla/code/admin/siteLater we will expand it to include information about the database tables used, available hooks, and any related mods that alter the way this page works.
That last part is probably one of the most important aspects of this documentation. Since Hubzilla can be modified using addons, widgets, and themes, and has hooks that can override the core code, it is useful to see everything in one place.
That way we avoid conflicts and breaking changes. For example, if core developers are refactoring the code, if they know that certain addons or themes depend on that code to be a certain way, then the changes can be coordinated in such a way where there are no sudden surprises that something stops working. At least, that is the plan. And on the flip side, third-party developers can understand what can and can't be overridden in the core using hooks.
But, as you can guess, this is going to be a huge undertaking. To address that, we make it a wiki, which allows us to grant access to other developers and technical writers who want to contribute. We will also be adding to the documentation over time as we build more stuff. So, initially, a lot of the documentation will be related to what we are currently working on.
I am sure it will be rough around the edges and incomplete for awhile, but we have to start somewhere.
Another interesting aspect is the integration with the new project management system that we are rolling out. When looking at the documentation, there will be a section that has a list of related tasks. And the related tasks will link back to this documentation.
This is what we are building. I think it will make a big difference and help contributors collaborate on Hubzilla and related projects.
