Hello,
On 23/01/2017 15:44, Daniel-Constantin Mierla wrote:
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:
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.
I created the markdown version for the tutorial to install Kamailio devel from git to make it easier to compare.
The html version build with mkdocs (http://mkdocs.org) is available in html format at:
- http://kamailio.org/docs/tutorials/kamailio-install-guide-git-devel/
Git repo is at:
- https://github.com/kamailio/kamailio-docs/tree/master/kamailio-install-guide...
Viewing the content via github:
- https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide...
You can compare with the old tutorial in the wiki:
- https://www.kamailio.org/wiki/install/devel/git
Again, the main reason of this discussion is not the look, but the collaboration mechanisms and tools behind building the docs and maintaining/versioning them.
Cheers, Daniel