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

[Annus Fictus]

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
>>>>>