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

[Daniel-Constantin Mierla]

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