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

[Annus Fictus]

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