Hi, for now they are just a few modules that include real examples in their doc. Usually, a module doc just shows examples of how to set each parameter or use each function, but there is not a "global" example.
I don't know if would be good to include a section "Examples" in the module doc template (it could saturate the info), or maybe a section "Examples" containing links to the wiki or external references.
What do you think about it?
Hello,
Iñaki Baz Castillo wrote:
Hi, for now they are just a few modules that include real examples in their doc. Usually, a module doc just shows examples of how to set each parameter or use each function, but there is not a "global" example.
I don't know if would be good to include a section "Examples" in the module doc template (it could saturate the info), or maybe a section "Examples" containing links to the wiki or external references.
What do you think about it?
I think this would be the most important task for the documentation, to add real-life example config how the functionality is used.
Stefan
Hola, Iñaki... Guys...
Aggregate "Examples" is a which issue on every documentation task... Users claim for it... BUT... (here comes the problem).. who will be responsible for write them? Who will do the check to ensure that they are workable ones? Who will maintain it over code changes? The natural answer would be "the developers.. who else knows better the capacities and use target of a code?"
And now, the other side: have the developers time and "which" to embrace this more work? I really don't think so...
But and the "Examples"? Well if they are really desired, than we still have two sources: the DOC-guys and the community (through a WIKI?). But I would exclude the DOC-guys, since they are focused on the DOC structure and compilation. Sure that as a side-effect they will learn a lot about functionalities and tips and twiks... but will still be only DOC-guys. So we stand with the community...
Now the big OSS challenge: how to make the community embrace this kind of work? For the the first write it's hard, but not so hard as to claim for actualization over time... and this arises another unforgetable issue: money and knowledge... people use to make money with there knowledge.... since the system is OSS, there diferential on the market is knowledge... and share examples implies to share knowledge... it's a delicate issue, but is real and is here and now.
After all this said and though, I would like to ask to for help on resolve this (Your sugestion but in a little different approach):
"As 'Examples-sections' are desired and really good (for support, learning, etc, etc, etc), how to define who will write and maintain it?"
Just before ending, I'd say that structure is not the biggest problem right now... it comes alone in the main structure discussion...
Saludos, Edson
-----Original Message----- From: openser-docs-bounces@lists.openser.org [mailto:openser-docs- bounces@lists.openser.org] On Behalf Of Iñaki Baz Castillo Sent: quarta-feira, 27 de fevereiro de 2008 09:25 To: openser-docs@lists.openser.org Subject: [OpenSER-Docs] Add examples in module documentation
Hi, for now they are just a few modules that include real examples in their doc. Usually, a module doc just shows examples of how to set each parameter or use each function, but there is not a "global" example.
I don't know if would be good to include a section "Examples" in the module doc template (it could saturate the info), or maybe a section "Examples" containing links to the wiki or external references.
What do you think about it?
-- Iñaki Baz Castillo ibc@in.ilimit.es
Openser-docs mailing list Openser-docs@lists.openser.org http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
On Wednesday 27 February 2008, Edson wrote:
[..] But and the "Examples"? Well if they are really desired, than we still have two sources: the DOC-guys and the community (through a WIKI?). But I would exclude the DOC-guys, since they are focused on the DOC structure and compilation. Sure that as a side-effect they will learn a lot about functionalities and tips and twiks... but will still be only DOC-guys. So we stand with the community... [..] Just before ending, I'd say that structure is not the biggest problem right now... it comes alone in the main structure discussion...
Hi Edson,
for the moment i care about the structure, to get the foundation right. After these are layed we should really care about the content, as you said, the structure is not our main problem.
I would like to add that i hope that this list will be mainly about the content. BTW, if anybody is not interested in this whole structure discussion, feel free to start right now in improving any existing documentation.
Cheers,
Henning
Hi, Henning...
You are right.. the structure definition IS for the moment. What I intended with my thoughts was to enlight that a "which" can bring a lot of responsabilities and side-effects in a middle/long shoot. The "example" topic is indeed very interesting and desired, but it brings/aggregates a lot of work, so just now, my concern is to first do the "must-have" things and after focus and the "which list".
Please, Iñaki, I not intended to make You give up from Your idea... far away from this interpretation... I just wanted to present my thoughts on the inherited/derived issues/problems and ask You for help...
Edson
-----Original Message----- From: Henning Westerholt [mailto:henning.westerholt@1und1.de] Sent: quarta-feira, 27 de fevereiro de 2008 10:22 To: openser-docs@lists.openser.org Cc: Edson; 'Iñaki Baz Castillo' Subject: Re: [OpenSER-Docs] Add examples in module documentation
On Wednesday 27 February 2008, Edson wrote:
[..] But and the "Examples"? Well if they are really desired, than we still
have
two sources: the DOC-guys and the community (through a WIKI?). But I
would
exclude the DOC-guys, since they are focused on the DOC structure and compilation. Sure that as a side-effect they will learn a lot about functionalities and tips and twiks... but will still be only DOC-guys. So we stand with the community... [..] Just before ending, I'd say that structure is not the biggest problem
right
now... it comes alone in the main structure discussion...
Hi Edson,
for the moment i care about the structure, to get the foundation right. After these are layed we should really care about the content, as you said, the structure is not our main problem.
I would like to add that i hope that this list will be mainly about the content. BTW, if anybody is not interested in this whole structure discussion, feel free to start right now in improving any existing documentation.
Cheers,
Henning
El Wednesday 27 February 2008 14:55:28 Edson escribió:
Please, Iñaki, I not intended to make You give up from Your idea... far away from this interpretation... I just wanted to present my thoughts on the inherited/derived issues/problems and ask You for help...
Sure, I kwno ;) In fact I aggre with you, it will be really a task to create and mantain these examples. But as Henning says, it will be a second problem. For now I just wanted to suggest a simple "Examples" section in the module doc template, and about what it should/could contain (long code examples? references to OpenSer wiki? external references?).
Best regards.
Hello,
Edson wrote:
Now the big OSS challenge: how to make the community embrace this kind of work? For the the first write it's hard, but not so hard as to claim for actualization over time... and this arises another unforgetable issue: money and knowledge... people use to make money with there knowledge.... since the system is OSS, there diferential on the market is knowledge... and share examples implies to share knowledge... it's a delicate issue, but is real and is here and now.
well, that is obviously true, but I hope that some developers are for example employed by companies in whose interest it is to commoditize also things a little bit more advanced than the most basic stuff in order to get a wider usage of these features and improve their quality by more extensive testing and sharing the cost of further development.
Gruß Stefan
On Wednesday 27 February 2008, Stefan Sayer wrote:
Now the big OSS challenge: how to make the community embrace this kind of work? For the the first write it's hard, but not so hard as to claim for actualization over time... and this arises another unforgetable issue: money and knowledge... people use to make money with there knowledge.... since the system is OSS, there diferential on the market is knowledge... and share examples implies to share knowledge... it's a delicate issue, but is real and is here and now.
well, that is obviously true, but I hope that some developers are for example employed by companies in whose interest it is to commoditize also things a little bit more advanced than the most basic stuff in order to get a wider usage of these features and improve their quality by more extensive testing and sharing the cost of further development.
Hi Stefan,
well, for the development of new (and the maintainance of existing) code this model works fairly well for the project. But for documentation it don't work, even if most people would admit that the lack of docs is a problem for them. Its hard to get even decent config file examples..
Newcomers join the project, have problems to get through the basics, and after they've learned the small piece of knowledge that they need for the moment, most of them forgot about the problem. We developers sometimes don't understand the problems of our users anymore, and for some time it was not really enforced thorough the project that features without documentation are almost useless..
But nobody have said this is an easy problem. :-)
It will not change overnight, but progress is inevitable if we keep trying to improve the situation. ;-)
Cheers,
Henning
-
Edson -
Henning Westerholt -
Iñaki Baz Castillo -
Stefan Sayer