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

Thu Jan 26 17:15:29 CET 2017

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