27 Feb
2008
27 Feb
'08
1:24 p.m.
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(a)in.ilimit.es
27 Feb
27 Feb
1:40 p.m.
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
--
Stefan Sayer
VoIP Services
stefan.sayer(a)iptego.com
www.iptego.com
iptego GmbH
Am Borsigturm 40
13507 Berlin
Germany
Amtsgericht Charlottenburg, HRB 101010
Geschaeftsfuehrer: Alexander Hoffmann
1:56 p.m.
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(a)lists.openser.org [mailto:openser-docs-
bounces(a)lists.openser.org] On Behalf Of Iñaki Baz Castillo
Sent: quarta-feira, 27 de fevereiro de 2008 09:25
To: openser-docs(a)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(a)in.ilimit.es
_______________________________________________
Openser-docs mailing list
Openser-docs(a)lists.openser.org
http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
2:21 p.m.
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
2:55 p.m.
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(a)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
3:20 p.m.
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.
--
Iñaki Baz Castillo
ibc(a)in.ilimit.es
2:33 p.m.
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
--
Stefan Sayer
VoIP Services
stefan.sayer(a)iptego.com
www.iptego.com
iptego GmbH
Am Borsigturm 40
13507 Berlin
Germany
Amtsgericht Charlottenburg, HRB 101010
Geschaeftsfuehrer: Alexander Hoffmann
3 Mar
3 Mar
2:13 p.m.
On Wednesday 27 February 2008, Stefan Sayer wrote:
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
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.
5897
days inactive
5902
days old
7 comments
4 participants
participants (4)
-
Edson -
Henning Westerholt -
Iñaki Baz Castillo -
Stefan Sayer