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: > > - 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. 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-git Viewing the content via github: - https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide-git/docs/index.md 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 -- 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 _______________________________________________ SIP Express Router (SER) and Kamailio (OpenSER) - sr-users mailing list sr-users@lists.sip-router.org http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
