Move examples to website?

[Christian Grobmeier <gr...@gmail.com>]

Hi all,

I have updated the examples and thought they would fit better in our
site than in our app directory. Here are my reasons:

- any sourcecode in the sourcecode folders should be tested, examples aren't
- examples on the homepage are probably the first thing users want to see
- examples in the sourcefolder are ok, but first you read the homepage
- one can copy/paste them from there too
- examples do not always run out of the box (for example server.php
which needs Net_Pear stuff). This may look a bit unprofessional if one
is trying out
- examples are very similar to each other. Just property files are different

What do you think?

Best,
Christian

Re: Move examples to website?

[Christian Grobmeier <gr...@gmail.com>]

Hi Christian,
sorry for my late reply. Your mail went under the wave of other mails.

Please see: ci.apache.org/projects/log4php
I have started to write user documentation. You may want to add /
correct something here,
since I think that your english is better than mine :-)

Additionally, I would appreciate good phpdoc class documentation too.
Can you help out?

If the examples would go directly to the class level doc and are in
the user docs of the website,
i think this would be good enough.
However, I like the idea of generating "something" :-)

Patches welcome!
best,
Christian


> More examples on the web site are certainly a good idea!
> We have the unit tests... Maybe we could put some unit tests in
> a special directory that gets converted to HTML and put on the web
> page. If those unit tests were well documented and very small then they
> could act as example. But in contrast to the usual examples they would
> then be known to always work and in addition count to the code coverage
> statistics. Of course this should not be done with all tests as some are
> just too cryptic to be used as an example.
>
> If that does not work out we could also try to put an how-to-use
> example on top of every class description and then extract it somehow
> for the website. This would have the benefit that our phpdoc would not
> be look so boring and also made sure that every major class has at
> least some kind of example. Experienced users who just search e.g. the
> syslog appender will directly go to the api docs anyway and would be
> happy to find an example there.
>
> bye,
>
> -christian-
>
>
>
>
>
>
> Am Mon, 17 Aug 2009 07:09:46 +0200
> schrieb Christian Grobmeier <gr...@gmail.com>:
>
>> Hi all,
>>
>> I have updated the examples and thought they would fit better in our
>> site than in our app directory. Here are my reasons:
>>
>> - any sourcecode in the sourcecode folders should be tested, examples
>> aren't
>> - examples on the homepage are probably the first thing users want to
>> see
>> - examples in the sourcefolder are ok, but first you read the homepage
>> - one can copy/paste them from there too
>> - examples do not always run out of the box (for example server.php
>> which needs Net_Pear stuff). This may look a bit unprofessional if one
>> is trying out
>> - examples are very similar to each other. Just property files are
>> different
>>
>> What do you think?
>>
>> Best,
>> Christian
>

Re: Move examples to website?

[Christian Hammers <ch...@lathspell.de>]

Hi

More examples on the web site are certainly a good idea!

We have the unit tests... Maybe we could put some unit tests in 
a special directory that gets converted to HTML and put on the web
page. If those unit tests were well documented and very small then they
could act as example. But in contrast to the usual examples they would
then be known to always work and in addition count to the code coverage
statistics. Of course this should not be done with all tests as some are
just too cryptic to be used as an example.

If that does not work out we could also try to put an how-to-use
example on top of every class description and then extract it somehow
for the website. This would have the benefit that our phpdoc would not
be look so boring and also made sure that every major class has at
least some kind of example. Experienced users who just search e.g. the
syslog appender will directly go to the api docs anyway and would be
happy to find an example there.

bye,

-christian-






Am Mon, 17 Aug 2009 07:09:46 +0200
schrieb Christian Grobmeier <gr...@gmail.com>:

> Hi all,
> 
> I have updated the examples and thought they would fit better in our
> site than in our app directory. Here are my reasons:
> 
> - any sourcecode in the sourcecode folders should be tested, examples
> aren't
> - examples on the homepage are probably the first thing users want to
> see
> - examples in the sourcefolder are ok, but first you read the homepage
> - one can copy/paste them from there too
> - examples do not always run out of the box (for example server.php
> which needs Net_Pear stuff). This may look a bit unprofessional if one
> is trying out
> - examples are very similar to each other. Just property files are
> different
> 
> What do you think?
> 
> Best,
> Christian