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

Annus Fictus annusfictus at gmail.com
Tue Jan 24 21:44:01 CET 2017


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
>




More information about the sr-users mailing list