[OpenSER-Docs] Add examples in module documentation

[Edson]

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 at lists.openser.org [mailto:openser-docs-
>bounces at lists.openser.org] On Behalf Of Iñaki Baz Castillo
>Sent: quarta-feira, 27 de fevereiro de 2008 09:25
>To: openser-docs at 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 at in.ilimit.es
>
>_______________________________________________
>Openser-docs mailing list
>Openser-docs at lists.openser.org
>http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs