Hello,
I want to start a discussion about some of the kamailio tutorials from the wiki, mainly those related to core cookbook, variables and transformations. They are now in dokuwiki at:
- https://www.kamailio.org/wiki/#cookbooks
The wiki served us pretty well so far, however the contributions there are not that active. From time to time we still get spammers, even we added restriction that only registered and authenticated users can write.
I am thinking that maybe people don't like creating yet another account just add some example or rephrase for clarity.
On the other hand, there are over 400 registered users, many of them I expect to be either made because if misunderstanding the purpose or by spammers that guessed the (sip) captcha (plenty of random usernames).
Besides that I think the wiki adds overhead when releasing a new version as each time we have to copy and paste old version content to a new set of pages and update the version number.
With the above in mind, I wonder if won't be better to store those tutorials in markdown format and use mkdocs.org or gitbook (https://github.com/GitbookIO/gitbook) tools to generate the html and host it in kamailio.org. The wiki will still be used to index them.
Among the benefits I see:
* store in github.com (a new repo, like: kamailio-docs) and all devs can contribute directly, other users can make pull requests
* create branches for each major version of kamailio and backport across them with git whenever is applicable
* the edit can be done directly via github.com website (similar to the wiki right now) and even read it directly from github in html transformed from markdown by github
* one can get them offline by cloning the git repo, use them or enhance when offline
Many if the tutorials will stay in the wiki, but I think those that are related to documenting per kamailio version should be migrated to gihub storage + markdown. If there is a strong pro opinion for this change, I can try to convert one of the cookbooks very soon so people can feel better the difference. If we get to a consensus, then I think we can have those tutorials in the new format for v5.0.
Should anyone have comments, other suggestions or improvements, let's put them on debate.
Cheers, Daniel