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.
Cheers, Daniel
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:
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...
Viewing the content via github:
- https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide...
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
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/#cookbooksThe 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 devscan contribute directly, other users can make pull requests
* create branches for each major version of kamailio and backportacross them with git whenever is applicable
* the edit can be done directly via github.com website (similar tothe 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 orenhance 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...
Viewing the content via github:
https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide...
You can compare with the old tutorial in the wiki:
- https://www.kamailio.org/wiki/install/devel/gitAgain, 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
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/#cookbooksThe 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 alldevs can contribute directly, other users can make pull requests
* create branches for each major version of kamailio and backportacross them with git whenever is applicable
* the edit can be done directly via github.com website (similar tothe 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 orenhance 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...
Viewing the content via github:
https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide...
You can compare with the old tutorial in the wiki:
- https://www.kamailio.org/wiki/install/devel/gitAgain, 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
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:
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/#cookbooksThe 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 alldevs can contribute directly, other users can make pull requests
* create branches for each major version of kamailio and backportacross them with git whenever is applicable
* the edit can be done directly via github.com website (similar tothe 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 orenhance 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...
Viewing the content via github:
-https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide...
You can compare with the old tutorial in the wiki:
- https://www.kamailio.org/wiki/install/devel/gitAgain, 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
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:
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/#cookbooksThe 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 alldevs can contribute directly, other users can make pull requests
* create branches for each major version of kamailio andbackport 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 orenhance 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...
Viewing the content via github:
-https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide...
You can compare with the old tutorial in the wiki:
- https://www.kamailio.org/wiki/install/devel/gitAgain, 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
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-docsThe 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/#cookbooksThe 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 alldevs can contribute directly, other users can make pull requests
* create branches for each major version of kamailio andbackport 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 orenhance 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...
Viewing the content via github:
-https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide...
You can compare with the old tutorial in the wiki:
- https://www.kamailio.org/wiki/install/devel/gitAgain, 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
Hello,
you can write it, for sure it will be appreciated by many. But I think it is not the kind of tutorial that needs to have a version for each kamailio major release. Anyhow, we can create another repository for HowTo-kind of tutorials.
Cheers, Daniel
On 27/01/2017 15:39, Annus Fictus wrote:
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-docsThe 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...
Viewing the content via github:
-https://github.com/kamailio/kamailio-docs/blob/master/kamailio-install-guide...
You can compare with the old tutorial in the wiki:
- https://www.kamailio.org/wiki/install/devel/gitAgain, 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
-
Annus Fictus -
Daniel-Constantin Mierla