how should merge be done, when function names differ? should we support both names or choose one?
for example, max_forwards module:
s:
maxfwd_process(max_value) maxfwd_at_least(min_value)
k:
mf_process_maxfwd_header(max_value) is_maxfwd_lt(max_value)
my vote is to take one that has better documentation.
-- juha
On Apr 20, 2009 at 12:59, Juha Heinanen jh@tutpro.com wrote:
how should merge be done, when function names differ? should we support both names or choose one?
for example, max_forwards module:
s:
maxfwd_process(max_value) maxfwd_at_least(min_value)
k:
mf_process_maxfwd_header(max_value) is_maxfwd_lt(max_value)
my vote is to take one that has better documentation.
My vote would be to merge the names (it should be a minimal effort to copy & paste and then change the name in the module interface).
Our initial goal is to minimize script changes for people upgrading from kamailio or ser to sip-router. In time we'll obsolete one name.
A special note regarding maxfwd: there seem to be other differences. At least a quick look at the ser version showed that it supports dynamic config changes (in this case max_limit can be changed anytime at runtime, e.g.: sercmd cfg.set_int_now maxfwd.max_limit 5).
Andrei
Andrei Pelinescu-Onciul writes:
My vote would be to merge the names (it should be a minimal effort to copy & paste and then change the name in the module interface).
i didn't understand how you merge names. will the resulting module have two names for the same function?
A special note regarding maxfwd: there seem to be other differences. At least a quick look at the ser version showed that it supports dynamic config changes (in this case max_limit can be changed anytime at runtime, e.g.: sercmd cfg.set_int_now maxfwd.max_limit 5).
i didn't find that in module readme. the policy should be that whatever is not documented, does not exist.
-- juha
On 20-04 13:21, Juha Heinanen wrote:
Andrei Pelinescu-Onciul writes:
My vote would be to merge the names (it should be a minimal effort to copy & paste and then change the name in the module interface).
i didn't understand how you merge names. will the resulting module have two names for the same function?
A special note regarding maxfwd: there seem to be other differences. At least a quick look at the ser version showed that it supports dynamic config changes (in this case max_limit can be changed anytime at runtime, e.g.: sercmd cfg.set_int_now maxfwd.max_limit 5).
i didn't find that in module readme. the policy should be that whatever is not documented, does not exist.
For new code maybe, but I wouldn't be so picky about existing code. I do not want to throw away stuff that already exists just because it is not documented.
Jan.
Jan Janak writes:
For new code maybe, but I wouldn't be so picky about existing code. I do not want to throw away stuff that already exists just because it is not documented.
yes, i need to soften my position.
undocumented features just makes merge much harder, because it is not enough to compare readme files. also, it more or less means that the party who has not documented its features needs to make the merge, because that party understands what the undocumented features are doing.
-- juha
On 20-04 14:16, Juha Heinanen wrote:
Jan Janak writes:
For new code maybe, but I wouldn't be so picky about existing code. I do not want to throw away stuff that already exists just because it is not documented.
yes, i need to soften my position.
undocumented features just makes merge much harder, because it is not enough to compare readme files. also, it more or less means that the party who has not documented its features needs to make the merge, because that party understands what the undocumented features are doing.
Nobody said it would be easy. I too had my share of this while I was trying to convert kamailio modules. Not everything can be documented in readmes, for example, there is a lot of changes in kamailio internals that I didn't understand and I had to ask Daniel, Henning, and others.
If you need to find the author of a particular change then you can use 'git blame' and talk to them directly. But I am afraid there is no way around browsing through the code and trying to spot what is different.
But yes, I find it reasonable to ask from people that all new code must be documented somehow (readme, wiki,...).
Jan.
Jan Janak schrieb:
On 20-04 14:16, Juha Heinanen wrote:
Jan Janak writes:
For new code maybe, but I wouldn't be so picky about existing code. I do not want to throw away stuff that already exists just because it is not documented.
yes, i need to soften my position.
undocumented features just makes merge much harder, because it is not enough to compare readme files. also, it more or less means that the party who has not documented its features needs to make the merge, because that party understands what the undocumented features are doing.
Nobody said it would be easy. I too had my share of this while I was trying to convert kamailio modules. Not everything can be documented in readmes, for example, there is a lot of changes in kamailio internals that I didn't understand and I had to ask Daniel, Henning, and others.
If you need to find the author of a particular change then you can use 'git blame' and talk to them directly. But I am afraid there is no way around browsing through the code and trying to spot what is different.
But yes, I find it reasonable to ask from people that all new code must be documented somehow (readme, wiki,...).
I prefer README as authoritative source - every feature commit should also add a feature descrption (e.g. do not write long commit messages but write the text into the README and then copy paste it into the commit message)
regards klaus
Klaus Darilion writes:
I prefer README as authoritative source - every feature commit should also add a feature descrption (e.g. do not write long commit messages but write the text into the README and then copy paste it into the commit message)
i agree and also, there should be a common format for readme file source files. if i look at modules/tm, it contains:
jh@taimen:/usr/src/orig/sip-router$ ls modules/tm/doc api.xml functions.xml Makefile params.xml tm.xml
and if i look at a k derived module, it has:
jh@taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc auth_radius_admin.xml auth_radius.xml
there is thus need to standardize doc format and have documentation of all common modules up to data, before we can even dream to announce this project to users.
-- juha
Juha Heinanen wrote:
Klaus Darilion writes:
I prefer README as authoritative source - every feature commit should also add a feature descrption (e.g. do not write long commit messages but write the text into the README and then copy paste it into the commit message)
i agree and also, there should be a common format for readme file source files. if i look at modules/tm, it contains:
jh@taimen:/usr/src/orig/sip-router$ ls modules/tm/doc api.xml functions.xml Makefile params.xml tm.xml
and if i look at a k derived module, it has:
jh@taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc auth_radius_admin.xml auth_radius.xml
Before sip-router started, I started an effort for SER to have all module documentation standardized into a manual page based on docbook sources.[0] The result is certainly optimal, for a user on a *nix system, doing "man tm" should be natural.
The source format is dubious, though. I eventually ended up with docbook since it is a standard of sorts and there are tools to make manpages out of the sources (although they need some tweaking). However, editing is as painful as it gets. For documentation, painful editing usually means it is not being done. So, if someone has a better suggestion for the source format, they are most welcome. Some lightweight markup like RST is probably a good idea, but then someone needs to write a RST-to-docbook converter (shouldn't be that hard) and we need some formating rules (not very hard either, pretty much everyone knows how manpages look).
Regards, Martin
[0] The git Web frontend's URL scheme sucks big time, but here is an example:
http://git.sip-router.org/cgi-bin/gitweb.cgi?p=ser_modules;a=blob;f=modules_...
We didn't check in the results, but here is how it looks like:
On 21-04 09:09, Martin Hoffmann wrote:
Juha Heinanen wrote:
Klaus Darilion writes:
I prefer README as authoritative source - every feature commit should also add a feature descrption (e.g. do not write long commit messages but write the text into the README and then copy paste it into the commit message)
i agree and also, there should be a common format for readme file source files. if i look at modules/tm, it contains:
jh@taimen:/usr/src/orig/sip-router$ ls modules/tm/doc api.xml functions.xml Makefile params.xml tm.xml
and if i look at a k derived module, it has:
jh@taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc auth_radius_admin.xml auth_radius.xml
Before sip-router started, I started an effort for SER to have all module documentation standardized into a manual page based on docbook sources.[0] The result is certainly optimal, for a user on a *nix system, doing "man tm" should be natural.
The source format is dubious, though. I eventually ended up with docbook since it is a standard of sorts and there are tools to make manpages out of the sources (although they need some tweaking). However, editing is as painful as it gets. For documentation, painful editing usually means it is not being done. So, if someone has a better suggestion for the source format, they are most welcome. Some lightweight markup like RST is probably a good idea, but then someone needs to write a RST-to-docbook converter (shouldn't be that hard) and we need some formating rules (not very hard either, pretty much everyone knows how manpages look).
I certainly agree with the idea that all new stuff should be documented, but I wonder whether we should revisit the system we write documentation in? I am personaly fine with docbook.
But if our goal is to produce plain text READMEs, wouldn't it make more sense to adopt something simpler, for example the dokuwiki format? It is easily readable as plain-text and we can edit it in the wiki and synchornize with READMEs in the repository.
It's just an idea...
Jan.
Jan Janak wrote:
But if our goal is to produce plain text READMEs, wouldn't it make more sense to adopt something simpler, for example the dokuwiki format? It is easily readable as plain-text and we can edit it in the wiki and synchornize with READMEs in the repository.
This sort of leads to the lightweight markup approach. Basically, add a small amount of markup and formatting rules to the README so that you can turn them into a man page, PDF, Wiki pages, you name it.
The Python people use RST everywhere -- the entire documentation basically is RST files (on docs.python.org you can even check the raw files). While I am personally not too fond of RST, it would be a good choice since obviously processing the stuff in Python is easy.
If we then define the required sections in the README file, we can write a little script for turning it into nroff or docbook or whatever.
Regards, Martin
Martin Hoffmann writes:
The Python people use RST everywhere -- the entire documentation basically is RST files (on docs.python.org you can even check the raw files). While I am personally not too fond of RST, it would be a good choice since obviously processing the stuff in Python is easy.
If we then define the required sections in the README file, we can write a little script for turning it into nroff or docbook or whatever.
fine, but how to turn current k module docs into that format?
-- juha
Juha Heinanen wrote:
Martin Hoffmann writes:
The Python people use RST everywhere -- the entire documentation basically is RST files (on docs.python.org you can even check the raw files). While I am personally not too fond of RST, it would be a good choice since obviously processing the stuff in Python is easy.
If we then define the required sections in the README file, we can write a little script for turning it into nroff or docbook or whatever.
fine, but how to turn current k module docs into that format?
Manually and over time.
Regards, Martin
Martin Hoffmann writes:
fine, but how to turn current k module docs into that format?
Manually and over time.
as i already mentioned, it is not long ago when we made a big reformatting effort of k modules. it is not good use of time to start it again.
-- juha
Juha Heinanen wrote:
Martin Hoffmann writes:
fine, but how to turn current k module docs into that format?
Manually and over time.
as i already mentioned, it is not long ago when we made a big reformatting effort of k modules. it is not good use of time to start it again.
Point taken. From where I stand, the documentation for many of the SER modules needs to be redone anyhow (hence me starting on that). So, if the K conventions are good enough, then you have the common format and the matter can be settled.
Although I still love the idea of having manpages.
Regards, Martin
On Tuesday 21 April 2009, Martin Hoffmann wrote:
Manually and over time.
as i already mentioned, it is not long ago when we made a big reformatting effort of k modules. it is not good use of time to start it again.
Point taken. From where I stand, the documentation for many of the SER modules needs to be redone anyhow (hence me starting on that). So, if the K conventions are good enough, then you have the common format and the matter can be settled.
Although I still love the idea of having manpages.
Hi Martin,
i thought you already wrote this script to convert the XML to man. We also did not check the man pages in (they can be easily generated from the XML source), so is there anything else missing in the SER for this?
Cheers,
Henning
Henning Westerholt wrote:
i thought you already wrote this script to convert the XML to man. We also did not check the man pages in (they can be easily generated from the XML source), so is there anything else missing in the SER for this?
Probably not. I will have a look into your stuff. I haven't done all that many modules, anyhow, since sip-router came up and I wanted to wait before investing more time. Seems to have been a smart move ;)
Regards, Martin
On Tuesday 21 April 2009, Martin Hoffmann wrote:
Henning Westerholt wrote:
i thought you already wrote this script to convert the XML to man. We also did not check the man pages in (they can be easily generated from the XML source), so is there anything else missing in the SER for this?
Probably not. I will have a look into your stuff. I haven't done all that many modules, anyhow, since sip-router came up and I wanted to wait before investing more time. Seems to have been a smart move ;)
Hi Martin,
not sure if its really compatible, it seems that SER uses a bit different dialect of docbook in its sources, but here is the converter XSL we use:
http://devel.kamailio.org/svn/trunk/doc/module-man.xsl
Cheers,
Henning
Jan Janak writes:
I certainly agree with the idea that all new stuff should be documented, but I wonder whether we should revisit the system we write documentation in? I am personaly fine with docbook.
in k we want to keep the tradition that ALL modules are fully documented. we don't accept a module or a new function in a module, unless it is fully documented. the system that is used to write the docs must be such that we can generate the doc at least as as txt and html. we have made a huge effort to write the readmes as they currently are. unless there is an automatic means to change their format, the format cannot be changed, i.e., manual change is out of question.
regarding common modules, before this project is announced to public, there thus needs to be k style documentation of all of them.
perhaps it was not a good idea to try to merge the modules after all if also documentation style is different in k and s, because we need to have two doc subdirs in all of them (one for k and another for s).
But if our goal is to produce plain text READMEs, wouldn't it make more sense to adopt something simpler, for example the dokuwiki format? It is easily readable as plain-text and we can edit it in the wiki and synchornize with READMEs in the repository.
generation of web page readmes has to be automatic from the module doc directory, since otherwise those two would never be in sync.
-- juha
On 21-04 11:11, Juha Heinanen wrote:
Jan Janak writes:
I certainly agree with the idea that all new stuff should be documented, but I wonder whether we should revisit the system we write documentation in? I am personaly fine with docbook.
in k we want to keep the tradition that ALL modules are fully documented. we don't accept a module or a new function in a module, unless it is fully documented. the system that is used to write the docs must be such that we can generate the doc at least as as txt and html. we have made a huge effort to write the readmes as they currently are. unless there is an automatic means to change their format, the format cannot be changed, i.e., manual change is out of question.
regarding common modules, before this project is announced to public, there thus needs to be k style documentation of all of them.
perhaps it was not a good idea to try to merge the modules after all if also documentation style is different in k and s, because we need to have two doc subdirs in all of them (one for k and another for s).
I don't understand this. In both cases it is xml based docbook. The structure of a docbook document is given. The fact that there are more files with boilerplate in modules coming from ser does not make it that much different.
Jan.
Jan Janak writes:
perhaps it was not a good idea to try to merge the modules after all if also documentation style is different in k and s, because we need to have two doc subdirs in all of them (one for k and another for s).
I don't understand this. In both cases it is xml based docbook. The structure of a docbook document is given. The fact that there are more files with boilerplate in modules coming from ser does not make it that much different.
fine if we can have READMEs autogenerated no matter which docbook files doc subdir contains.
-- juha
On 21-04 11:24, Juha Heinanen wrote:
Jan Janak writes:
perhaps it was not a good idea to try to merge the modules after all if also documentation style is different in k and s, because we need to have two doc subdirs in all of them (one for k and another for s).
I don't understand this. In both cases it is xml based docbook. The structure of a docbook document is given. The fact that there are more files with boilerplate in modules coming from ser does not make it that much different.
fine if we can have READMEs autogenerated no matter which docbook files doc subdir contains.
Of course, that will be possible. I don't know what were the steps to generate READMEs in kamailio, in ser modules we added a Makefile in each documentation directory and you can just type make txt to generate the README or make html to generat HTML based documentation.
We can either add Makefiles to modules in modules_k or import the kamailio system. But in any case we will be using the same tools and templates to generate READMEs.
Jan.
On Tuesday 21 April 2009, Jan Janak wrote:
perhaps it was not a good idea to try to merge the modules after all if also documentation style is different in k and s, because we need to have two doc subdirs in all of them (one for k and another for s).
I don't understand this. In both cases it is xml based docbook. The structure of a docbook document is given. The fact that there are more files with boilerplate in modules coming from ser does not make it that much different.
fine if we can have READMEs autogenerated no matter which docbook files doc subdir contains.
Of course, that will be possible. I don't know what were the steps to generate READMEs in kamailio, in ser modules we added a Makefile in each documentation directory and you can just type make txt to generate the README or make html to generat HTML based documentation.
Hi Jan,
module documentation in kamailio can be generated with (e.g. in old trunk):
- make modules-readme
This will generate the READMEs in all module directories, from the source in the respective 'doc' sub directory, for all modules that are not in the exclude_modules list. You can specify a certain module with "make modules-readme modules=$module_name" as usual.
- modules-docbook-html - modules-docbook-man - modules-docbook-pdf
will generates the respective output format in the module directory as well.
We can either add Makefiles to modules in modules_k or import the kamailio system. But in any case we will be using the same tools and templates to generate READMEs.
Sounds good, i prefer to not have two different documentation formats for modules in our tree.
Cheers,
Henning
On Tuesday 21 April 2009, Martin Hoffmann wrote:
Before sip-router started, I started an effort for SER to have all module documentation standardized into a manual page based on docbook sources.[0] The result is certainly optimal, for a user on a *nix system, doing "man tm" should be natural.
Hi Martin,
i also provided man pages for all kamailio modules with a similar approach like you did, by writing a XSL. But we don't used the docbook to man infrastructure like you did, instead we wrote a own small converter script.
Man pages in kamailio trunk and 1.5.0 release can be generated with make modules-docbook-man, and are also included in the debian packages, if you want to take a look.
The source format is dubious, though. I eventually ended up with docbook since it is a standard of sorts and there are tools to make manpages out of the sources (although they need some tweaking). However, editing is as painful as it gets.
I don't think that docbook is really that painful. If you look at a typical README source, e.g. for tm [1] then one needs to only master a few tags. This is not too hard, IMHO.
For documentation, painful editing usually means it is not being done. So, if someone has a better suggestion for the source format, they are most welcome. Some lightweight markup like RST is probably a good idea, but then someone needs to write a RST-to-docbook converter (shouldn't be that hard) and we need some formating rules (not very hard either, pretty much everyone knows how manpages look).
The docbook stuff has also some advantages, it can be checked against a stylesheet to see if the document is well formed, it really easy be convert into different outputs, like HTML, PDF, man-pages and so on..
Cheers,
Henning
On Tuesday 21 April 2009, Henning Westerholt wrote:
I don't think that docbook is really that painful. If you look at a typical README source, e.g. for tm [1] then one needs to only master a few tags. This is not too hard, IMHO.
Forget the link to the doc:
[1] http://devel.kamailio.org/svn/branches/1.5/modules/tm/doc/tm_admin.xml
Cheers,
Henning
Henning Westerholt wrote:
i also provided man pages for all kamailio modules with a similar approach like you did, by writing a XSL. But we don't used the docbook to man infrastructure like you did, instead we wrote a own small converter script.
Didn't know that (Yes, I am rather lazy). I will have a look into it. If you already have a lot of documentation in a certain format, we should probably reuse it, if it fullfills all requirements (which are not actually defined, of course).
The source format is dubious, though. I eventually ended up with docbook since it is a standard of sorts and there are tools to make manpages out of the sources (although they need some tweaking). However, editing is as painful as it gets.
I don't think that docbook is really that painful.
This may turn into an endless and rather pointless discussion, so I just shut up. I did choose docbook for my stuff, too, after all.
Regards, Martin
Martin,
On 21-04 09:09, Martin Hoffmann wrote:
Juha Heinanen wrote:
Klaus Darilion writes:
I prefer README as authoritative source - every feature commit should also add a feature descrption (e.g. do not write long commit messages but write the text into the README and then copy paste it into the commit message)
i agree and also, there should be a common format for readme file source files. if i look at modules/tm, it contains:
jh@taimen:/usr/src/orig/sip-router$ ls modules/tm/doc api.xml functions.xml Makefile params.xml tm.xml
and if i look at a k derived module, it has:
jh@taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc auth_radius_admin.xml auth_radius.xml
Before sip-router started, I started an effort for SER to have all module documentation standardized into a manual page based on docbook sources.[0] The result is certainly optimal, for a user on a *nix system, doing "man tm" should be natural.
The source format is dubious, though. I eventually ended up with docbook since it is a standard of sorts and there are tools to make manpages out of the sources (although they need some tweaking). However, editing is as painful as it gets. For documentation, painful editing usually means it is not being done. So, if someone has a better suggestion for the source format, they are most welcome. Some lightweight markup like RST is probably a good idea, but then someone needs to write a RST-to-docbook converter (shouldn't be that hard) and we need some formating rules (not very hard either, pretty much everyone knows how manpages look).
So did you generate the manpages from docbook after all? Or does it use some special syntax/markings? Would it be possible to generate man pages from the docbook documentation in modules?
Jan.
Jan Janak wrote:
So did you generate the manpages from docbook after all? Or does it use some special syntax/markings? Would it be possible to generate man pages from the docbook documentation in modules?
Docbook has some markup for manpages already. I used that:
http://www.oasis-open.org/docbook/documentation/reference/html/reference.htm...
On top of that I defined a bunch of elements and a stylesheet to get the manpages I want when I run them through
http://docbook2x.sourceforge.net/
They are still not perfect, but a lot better then the vanilla stuff.
Regards, Martin
On 04/21/2009 07:36 AM, Juha Heinanen wrote:
[...]
there is thus need to standardize doc format and have documentation of all common modules up to data, before we can even dream to announce this project to users.
if we wait for something perfect, then we will fail. This is open source and as soon as we get community involved, the project evolves much better. Couple of us worked full time for the past two months to get the modules integrated. This cannot last for too long time and I prefer to get out with something that is not that perfect, but in this way get more potential work force.
Nobody will get a penny for digging up and write documentation. From past experience, docs achievements in openser was done with large contribution of the community. From the group involved now, there are not so many that contributed to the wiki or the rest of docs resources so far, therefore we need more to help here.
Cheers, Daniel
Daniel-Constantin Mierla writes:
if we wait for something perfect, then we will fail.
s-r cannot be worse that k k from doc point of view. it is totally unacceptable to me if we start to accept modules or functions w/o documentation.
This is open source and as soon as we get community involved, the project evolves much better.
community is not able to write docs for common modules, e.g., tm.
Nobody will get a penny for digging up and write documentation. From past experience, docs achievements in openser was done with large contribution of the community.
i don't remember that user would have written many (or any) module docs. each developer, who is responsible of a module, has to take care of it. wiki is easier to get help with.
-- juha
On 04/21/2009 10:14 AM, Juha Heinanen wrote:
Daniel-Constantin Mierla writes:
if we wait for something perfect, then we will fail.
s-r cannot be worse that k k from doc point of view. it is totally unacceptable to me if we start to accept modules or functions w/o documentation.
all K modules have the same docs, so if you use them you have all you need. common tm is pretty well documented now.
If you work to merge some modules then you have to do the doc part as well.
This is open source and as soon as we get community involved, the project evolves much better.
community is not able to write docs for common modules, e.g., tm.
Why not? There are very experienced users in both sides. Many of missing functions and parameters from docs were reported by users. You jump to a conclusion without even trying to ask for help and see the results.
Nobody will get a penny for digging up and write documentation. From past experience, docs achievements in openser was done with large contribution of the community.
i don't remember that user would have written many (or any) module docs. each developer,
Olle E. Johansson provided lot of doc updates for doxygen and modules.
who is responsible of a module, has to take care of it.
What I do not understand is which module you need and lacks of documentation? You have all K modules very well documented. Many S modules I went though have good documentation, but will take some time to get all sync'ed, updated and in same format (although we can live with different formats as long as we can get html and txt).
I see no show stopper with the documentation as it is. If someone is missing something, he/she is free to help. If cannot get something from the source code, then can ask here for hints from the developer. We talk here about modules that exist, not about new contributions.
I have seen here recently lot of useful information about building system (Makefile) and not only, but none digested it in a wiki page.
wiki is easier to get help with.
It can accept extensions to module docs. For example in openser there are wiki pages for avp_db_query(), tm module and other. Latter can be imported to module's docbook.
Cheers, Daniel
Juha Heinanen wrote:
Daniel-Constantin Mierla writes:
This is open source and as soon as we get community involved, the project evolves much better.
community is not able to write docs for common modules, e.g., tm.
Why not? Everyone who can read code can write documentation. Granted, tm is tricky, but the developers can read over it and point out mistakes.
Regards, Martin
On Tuesday 21 April 2009, Martin Hoffmann wrote:
community is not able to write docs for common modules, e.g., tm.
Why not? Everyone who can read code can write documentation. Granted, tm is tricky, but the developers can read over it and point out mistakes.
Hi Martin,
sure, but the persons that should responsible for this documentation in the first place is the developer. He/ She is the persons that knows the module and its caveats the best. And in my experiences this make also sense from a developer perspective, one gets a bit tired answering the same user questions again and again.
Later extensions, cleanups, spelling fixes and bug reporting against the docs, this is what can be efficient be done from the community.
Cheers,
Henning
Henning Westerholt wrote:
On Tuesday 21 April 2009, Martin Hoffmann wrote:
community is not able to write docs for common modules, e.g., tm.
Why not? Everyone who can read code can write documentation. Granted, tm is tricky, but the developers can read over it and point out mistakes.
sure, but the persons that should responsible for this documentation in the first place is the developer.
True. But this is somewhat different from "community is not able to write docs". For the modules that are there just now and pretty old, I am happy to write the docs, even though I am not planning on maintaining them.
But I think this topic is somewhat exhausted: Seems to me we can agree on requiring documentation for modules and using K's formats for now since K has a gigantic advance there.
Regards, Martin
On 21-04 10:41, Martin Hoffmann wrote:
Juha Heinanen wrote:
Daniel-Constantin Mierla writes:
This is open source and as soon as we get community involved, the project evolves much better.
community is not able to write docs for common modules, e.g., tm.
Why not? Everyone who can read code can write documentation. Granted, tm is tricky, but the developers can read over it and point out mistakes.
You actually have to understand the code to be able to document it properly. Sure, you can always hire a technical writer who will produce boilerplate like documentation, but I doubt that such documentation will be of much use.
Developers are in the best position to write documentation, because they can actually document the ideas behind the code.
But now we are starting a philosophical debate again, sorry, but I couldn't resist :-).
Jan.
Jan Janak wrote:
On 21-04 10:41, Martin Hoffmann wrote:
Juha Heinanen wrote:
Daniel-Constantin Mierla writes:
This is open source and as soon as we get community involved, the project evolves much better.
community is not able to write docs for common modules, e.g., tm.
Why not? Everyone who can read code can write documentation. Granted, tm is tricky, but the developers can read over it and point out mistakes.
You actually have to understand the code to be able to document it properly.
I am quite aware of that. But the amount of familiarity with the code necessary to write useful documentation differs. Modules like xlog or acc are easy and even someone new to SER code can extract the necessary information. tm is the other extreme. Figuring out what the module will do with ACKs and CANCELs is a task for several hours.
But interstingly enough, this latter point also shows that documentation written by developers is necessarily good either. Neither K nor SER document the very subtle and occassionally unexpected behaviour.
Sure, you can always hire a technical writer who will produce boilerplate like documentation, but I doubt that such documentation will be of much use.
The main skill of a good technical writer is to ask the right questions. Sure, they are a very rare breed, but if you happen to run across one, you will afterwards understand your own code better.
Regards, Martin
On 21-04 13:24, Martin Hoffmann wrote:
Jan Janak wrote:
On 21-04 10:41, Martin Hoffmann wrote:
Juha Heinanen wrote:
Daniel-Constantin Mierla writes:
This is open source and as soon as we get community involved, the project evolves much better.
community is not able to write docs for common modules, e.g., tm.
Why not? Everyone who can read code can write documentation. Granted, tm is tricky, but the developers can read over it and point out mistakes.
You actually have to understand the code to be able to document it properly.
I am quite aware of that. But the amount of familiarity with the code necessary to write useful documentation differs. Modules like xlog or acc are easy and even someone new to SER code can extract the necessary information. tm is the other extreme. Figuring out what the module will do with ACKs and CANCELs is a task for several hours.
But interstingly enough, this latter point also shows that documentation written by developers is necessarily good either. Neither K nor SER document the very subtle and occassionally unexpected behaviour.
Maybe neither k. nor ser developers are aware of the subtle, unexpected behaviour. That wouldn't surprise me :-).
Jan.
On Tuesday 21 April 2009, Daniel-Constantin Mierla wrote:
if we wait for something perfect, then we will fail. This is open source and as soon as we get community involved, the project evolves much better. Couple of us worked full time for the past two months to get the modules integrated. This cannot last for too long time and I prefer to get out with something that is not that perfect, but in this way get more potential work force.
Hi Daniel,
i agree. But then we should communicate this correctly. Instead of announcing something that is almost done, we need to point out clearly the areas where issues exists, and also providing pointers where help is really appreciated.
Nobody will get a penny for digging up and write documentation.
Well, my employee also pays me to do work at the documentation (in kamailio so far). So it seems that some people did care in this areas too. If this is a capacity or resource problem with regards to some developing efforts, perhaps one of the (bigger) companies involved here can think about hiring a technical writer? Just an idea. :-)
From past experience, docs achievements in openser was done with large contribution of the community. From the group involved now, there are not so many that contributed to the wiki or the rest of docs resources so far, therefore we need more to help here.
The basic foundation were not done from the community IMHO, but i agree, we could really use more help here.
Cheers,
Henning
21 apr 2009 kl. 11.39 skrev Henning Westerholt:
On Tuesday 21 April 2009, Daniel-Constantin Mierla wrote:
if we wait for something perfect, then we will fail. This is open source and as soon as we get community involved, the project evolves much better. Couple of us worked full time for the past two months to get the modules integrated. This cannot last for too long time and I prefer to get out with something that is not that perfect, but in this way get more potential work force.
Hi Daniel,
i agree. But then we should communicate this correctly. Instead of announcing something that is almost done, we need to point out clearly the areas where issues exists, and also providing pointers where help is really appreciated.
In asterisk, we've defined these as "Janitor projects" - projects where the community can step in and help to clean up stuff with no requirements of them being full-time project developers. Indicating an easy way to get active.
We should define a new doxygen tag, or use the "\todo" tag for indicating stuff that needs some love, help and understanding.
/O
Hello,
On 04/21/2009 11:39 AM, Henning Westerholt wrote:
On Tuesday 21 April 2009, Daniel-Constantin Mierla wrote:
if we wait for something perfect, then we will fail. This is open source and as soon as we get community involved, the project evolves much better. Couple of us worked full time for the past two months to get the modules integrated. This cannot last for too long time and I prefer to get out with something that is not that perfect, but in this way get more potential work force.
Hi Daniel,
i agree. But then we should communicate this correctly. Instead of announcing something that is almost done,
I am not sure what you think the announcement would be, so I cannot comment.
What is almost done? I want to tell people that they can start playing with sip-router and K modules are there. In this way we learn what are the most used parts and make them work quicker. There is still lot of work to do, in regard to MI, statistics, additional processes. I prefer to work on something people use, rather than doing blind coding. I am not using most of the modules out there, therefore I am not able to test them properly.
Somehow I feel you think about a release -- we are far from there.
we need to point out clearly the areas where issues exists, and also providing pointers where help is really appreciated.
Are you happy with K documentation? Well, main page of kamailio.org has in bottom right corner a poll, it is there for quire some time. Guess what community think needs to be improved. Documentation will never be satisfactory for everybody, but it grows with the number of people using the application.
Nobody will get a penny for digging up and write documentation.
Well, my employee also pays me to do work at the documentation (in kamailio so far). So it seems that some people did care in this areas too. If this is a capacity or resource problem with regards to some developing efforts, perhaps one of the (bigger) companies involved here can think about hiring a technical writer?
I think there are companies that paid full time developers in the last months for the integration work. If there are other companies willing to fund, they are more than welcome.
Just an idea. :-)
From past experience, docs achievements in openser was done with large contribution of the community. From the group involved now, there are not so many that contributed to the wiki or the rest of docs resources so far, therefore we need more to help here.
The basic foundation were not done from the community IMHO,
I think all modules have docs, but not all up to date. The foundation is there, take a module, digg the sources and add what is missing in the readme. Even simply listing the functions and parameters to docbook with the note: "Needs content" is a step forward and great help. It is pretty simple to get out of mod interface: - parameter name and type - function name, number of parameters, where it can be used - name for exported PV, MI/RPC commands, ...
Others can come latter and complete.
Cheers, Daniel
but i agree, we could really use more help here.
On Tuesday 21 April 2009, Daniel-Constantin Mierla wrote:
What is almost done? I want to tell people that they can start playing with sip-router and K modules are there. In this way we learn what are the most used parts and make them work quicker. There is still lot of work to do, in regard to MI, statistics, additional processes. I prefer to work on something people use, rather than doing blind coding. I am not using most of the modules out there, therefore I am not able to test them properly.
Somehow I feel you think about a release -- we are far from there.
Hi Daniel,
ok, perhaps i misunderstood you here, just want to make it sure that we don't create false expectations.
we need to point out clearly the areas where issues exists, and also providing pointers where help is really appreciated.
Are you happy with K documentation? Well, main page of kamailio.org has in bottom right corner a poll, it is there for quire some time. Guess what community think needs to be improved. Documentation will never be satisfactory for everybody, but it grows with the number of people using the application.
Sure, i know that we've many issues in kamailio documentation, and the poll you mentioned mirrors also my impressions i got from user contacts. For a project of this size there are always several issues in docs, as well in the code.
The basic foundation were not done from the community IMHO,
I think all modules have docs, but not all up to date. The foundation is there, take a module, digg the sources and add what is missing in the readme. Even simply listing the functions and parameters to docbook with the note: "Needs content" is a step forward and great help. It is pretty simple to get out of mod interface:
- parameter name and type
- function name, number of parameters, where it can be used
- name for exported PV, MI/RPC commands, ...
Others can come latter and complete.
Good suggestion, perhaps we can start a wiki page with modules that needs some work on the documentation side, or open bug reports against them.
Cheers,
Henning
Henning Westerholt writes:
Sure, i know that we've many issues in kamailio documentation, and the poll you mentioned mirrors also my impressions i got from user contacts. For a project of this size there are always several issues in docs, as well in the code.
k docs are MUCH better than in an average open source project and we should keep it that way also in sip-router. it just affects those modules that in sip-router replace k modules.
-- juha
On 21-04 13:25, Juha Heinanen wrote:
Henning Westerholt writes:
Sure, i know that we've many issues in kamailio documentation, and the poll you mentioned mirrors also my impressions i got from user contacts. For a project of this size there are always several issues in docs, as well in the code.
k docs are MUCH better than in an average open source project and we should keep it that way also in sip-router. it just affects those modules that in sip-router replace k modules.
In that case I suggest we mandate that, when such a replacement happens, we have to make sure that the documentation is there and up-to-date. Modules are only replaced when they have the same functionality, so it is likely that the documentation from kamailio can be reused. For the rest we need to write.
Does this seem reasonable?
Jan.
Jan Janak writes:
In that case I suggest we mandate that, when such a replacement happens, we have to make sure that the documentation is there and up-to-date. Modules are only replaced when they have the same functionality, so it is likely that the documentation from kamailio can be reused. For the rest we need to write.
Does this seem reasonable?
yes, that is reasonable. so did we decide that common modules will use k readme style and generation script?
-- juha
On 21-04 14:12, Juha Heinanen wrote:
Jan Janak writes:
In that case I suggest we mandate that, when such a replacement happens, we have to make sure that the documentation is there and up-to-date. Modules are only replaced when they have the same functionality, so it is likely that the documentation from kamailio can be reused. For the rest we need to write.
Does this seem reasonable?
yes, that is reasonable. so did we decide that common modules will use k readme style and generation script?
Yes, the README style is the same as in ser modules and I'll see if we have targets in our makefile system equivalent with what Henning describe and if not then we'll add it.
Jan.
On 21-04 08:36, Juha Heinanen wrote:
Klaus Darilion writes:
I prefer README as authoritative source - every feature commit should also add a feature descrption (e.g. do not write long commit messages but write the text into the README and then copy paste it into the commit message)
i agree and also, there should be a common format for readme file source files. if i look at modules/tm, it contains:
jh@taimen:/usr/src/orig/sip-router$ ls modules/tm/doc api.xml functions.xml Makefile params.xml tm.xml
and if i look at a k derived module, it has:
jh@taimen:/usr/src/orig/sip-router$ ls modules/auth_radius/doc auth_radius_admin.xml auth_radius.xml
there is thus need to standardize doc format and have documentation of all common modules up to data, before we can even dream to announce this project to users.
It does not really matter how many files there are. In both cases it is xml based docbook that is used to produce a single document.
The only structure difference I can see is that we start our docbook tree with a <section> element, while kamailio modules start with <book>. This only makes a difference if you process the sources within a larger collection, i.e. we wanted to be able to insert module documentation within a larger document and starting with <section> is more flexible there because you can insert it anywhere in the documentation tree.
But in most cases the documentation in each module is processed separatetely and most often it is used to generate README files, and there it does not matter if the document starts with <section> or <book>.
The fact that ser modules sometimes lack up-to-date documentation is another issue.
Jan.
On Monday 20 April 2009, Klaus Darilion wrote:
I prefer README as authoritative source - every feature commit should also add a feature descrption (e.g. do not write long commit messages but write the text into the README and then copy paste it into the commit message)
Hi Klaus,
this is a good point. Indeed, our users will not look up the commit logs in the archives or the Changelog, we need to have this information in a common place, the module docs and core cookbook.
Cheers,
Henning
-
Andrei Pelinescu-Onciul -
Daniel-Constantin Mierla -
Henning Westerholt -
Jan Janak -
jh＠tutpro.com -
Klaus Darilion -
Martin Hoffmann -
Olle E. Johansson