Icinga
Restructure the training material
The training material evolved quite a bit over time, maybe it is time to rethink the structure.
This issue meant to gather ideas.
The training module includes many "products" from the Icinga Web stack. Not only Icinga Web 2 itself anymore.
When I'm looking for something, the first thing I do is to search for the "product" I want to do something with. From my point of view, it would therefore make sense to group the products into individual subfolders. (Icinga Web 2, IcingaDB-Web, IPL, etc.). Within these subfolders, the existing structure under docs/ could then be used. Or, if necessary, additional folders can be created (ipl-web, ipl-html, etc.)
This structure would ensure that you know what you are looking for, but it would improve the search significantly. In addition, you could find everything about a "product" at one place. This would also leave room for an extension of individual topics or even further "products" from the Icinga Web stack.
The big change would be the conversion to a "documentation page" instead of step-by-step training.
Current Topics:
- CLI
- Structure of a web module
- IPL introduction
- IPL databases, HTML, Forms
- Icinga Web libraries
- Icinga Web permission/restrictions
- Icinga Web configuration
- Icinga Web resources
- Hooks
- Themes
- Translations
- Third party libraries
Possible grouping:
- Icinga Web Module Introduction
- Icinga Web Module Core elements (translations, its PHP classes, permission, restrictions, configuration, resources, CLI, etc)
- The IPL
- Themes and CSS (could be extended with available Icinga LESS goodies)
not sure where to fit them elsewhere:
- Hooks
- Third party libraries
- Including other Icinga Web modules (e.g. icingadb, director, etc)
I think, first and foremost, it is important to define for whom you want to provide the training module. As a beginner in development with basic PHP knowledge, I found it very useful to have additional video tutorials. It was also helpful to follow an example and use the content for my own project.
I believe that documentation would serve a different purpose and cater to other use cases. Perhaps you could structure the content into A) documentation for search functionality and daily use, and B) training for developers to learn how to develop a web module for their own use cases.
A) documentation for search functionality and daily use, and B) training for developers to learn how to develop a web module for their own use cases.
Valid distinction. Right now it's a mix of both, with the origin being a training for developers (that already are familiar with PHP and various web technologies and development patterns). This should be the focus in my opinion.
I think a proper framework/development documentation should not be the goal of this repository. If there ever is a framework documentation it should be placed here icinga.com/docs and should be structured as such.