[sr-dev] RFC: Kamailio tutorials/cookbooks/docs - wiki or markdown

[Daniel-Constantin Mierla]

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