[SR-Users] RFC: Kamailio tutorials/cookbooks/docs - wiki or markdown

[Daniel-Constantin Mierla]

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

-- 
Daniel-Constantin Mierla
www.twitter.com/miconda -- www.linkedin.com/in/miconda
Kamailio Advanced Training - Mar 6-8 (Europe) and Mar 20-22 (USA) - www.asipto.com
Kamailio World Conference - May 8-10, 2017 - www.kamailioworld.com