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

Tue Jan 31 09:24:11 CET 2017

Hello,

you can write it, for sure it will be appreciated by many. But I think
it is not the kind of tutorial that needs to have a version for each
kamailio major release. Anyhow, we can create another repository for
HowTo-kind of tutorials.

Cheers,
Daniel

On 27/01/2017 15:39, Annus Fictus wrote:
> Hello,
>
> I'd like write a HowTo dedicated to LCR module implementation.
>
> Regards
>
>
> El 26/01/2017 a las 11:15, Daniel-Constantin Mierla escribió:
>> Hello,
>>
>> follow the usual contribution process recommended by github,
>> respectively the pull requests. That means:
>>
>>    - clone the kamailio/kamailio-docs repository to your account
>>    - add the tutorial in your cloned repository
>>    - when it is ready make a pull request back to origin repository
>>
>> You can search on the web for pull requests on github, there are plenty
>> of articles, here are two links to start with:
>>
>>    - https://help.github.com/articles/about-pull-requests/
>>    - https://help.github.com/articles/creating-a-pull-request/
>>
>> I would suggest to discuss first on the mailing list about the tutorial
>> you want to add to see if it is suitable for hosting it there. The scope
>> for kamailio-docs repository is to store the core cookbooks and common
>> interest tutorials that may depend on kamailio versions, which are now
>> in the wiki, but of course new topics can be added. Any kind of tutorial
>> is welcome to be contributed to Kamailio, but some may not fit inside
>> kamailio-docs repository (e.g., it may be published on the website or
>> wiki).
>>
>> Cheers,
>> Daniel
>>
>> On 26/01/2017 16:13, Annus Fictus wrote:
>>> Hello,
>>>
>>> If I have a github accunt can I write a new HowTo?
>>>
>>> If i can, how?
>>>
>>> Regards
>>>
>>>
>>> El 26/01/2017 a las 04:52, Daniel-Constantin Mierla escribió:
>>>> Hello,
>>>>
>>>> some updates ...
>>>>
>>>> I created the kamailio-docs repository on github and converted two of
>>>> the wiki tutorials for installing Kamailio. Actualy it is a bit more
>>>> than just converting, some new content being added.
>>>>
>>>> The repository on github can be found at:
>>>>
>>>>     * https://github.com/kamailio/kamailio-docs
>>>>
>>>> The tutorials done so far are about installing kamailio devel from git
>>>> and installing on debian from packages -- generated output
>>>> available at:
>>>>
>>>>     *
>>>> http://kamailio.org/docs/tutorials/devel/kamailio-install-guide-git/
>>>>
>>>>     *
>>>> http://kamailio.org/docs/tutorials/devel/kamailio-install-guide-deb/
>>>>
>>>> The developers should have commit access on kamailio-docs
>>>> repository (if
>>>> anyone faces issues, let me know). The broad community can contribute
>>>> via github pull requests.
>>>>
>>>> I hope many will start to help and convert the own favorite tutorials!
>>>>
>>>> Cheers,
>>>> Daniel
>>>>
>>>>
>>>> On 24/01/2017 21:44, Annus Fictus wrote:
>>>>> hello,
>>>>>
>>>>> I think is a good way to improve Kamailio documentation.
>>>>>
>>>>> Thank you
>>>>>
>>>>> Regards
>>>>>
>>>>> El 24/01/2017 a las 09:50, Daniel-Constantin Mierla escribió:
>>>>>> 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