Examples folder

[ravage84]

@pmjones similar to the resources folder (#12), I often have an examples folder in my packages.

I'm aware that this is kind of documentation but since I want to make it easy for people, which are checking out my libararies, I often include easy to find and easy to execute example scripts in the root folder under examples.

It seems I am not the only one:

• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L16 examples/ 1748
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L40 example/ 698
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L316 Example/ 31
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L322 Examples/ 31
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L860 _examples/ 6
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L953 code-examples/ 5
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L1664 _example/ 2
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L2130 example-scripts/ 2
• https://github.com/php-pds/skeleton_research/blob/1.x/results/01-dirs.txt#L2288 example code/ 2

But I guess this folder is not as important as the other ones, so it could be included as a recommendation instead?

[pmjones]

I went back-and-forth a bit on this myself. Here is the main issue: if we put "examples" into its own category, it becomes even less-common than bin/ directory, and doesn't hit the lower bound of 1-in-20 (5%) for consideration. This is from an alternative run on the research:

documentation directory     4142    6.3%
    docs/   2763    4.211%
    doc/    1198    1.826%
    documentation/  58  0.088%
    guide/  55  0.084%
    manual/ 42  0.064%
    phpdoc/ 19  0.029%
    usage/  7   0.011%
executables directory       3416    5.2%
    bin/    2747    4.186%
    scripts/    411 0.626%
    console/    154 0.235%
    cli/    51  0.078%
    script/ 33  0.05%
    shell/  20  0.03%
examples directory      3020    4.6%
    examples/   1748    2.664%
    example/    698 1.064%
    demo/   297 0.453%
    samples/    134 0.204%
    sample/ 80  0.122%
    demos/  58  0.088%
    demo-files/ 3   0.005%
    demo-data/  2   0.003%

Having said that, one other person has brought this up to me privately, so I am open to modifying the "docs" phrasing to remove references to examples. Would that suffice?

[ravage84]

Thanks for the explanation.

Yes and no. Yes, as it would allow to have an examples folder again. But no, as it wouldn't guide people as good as it does now.

[pmjones]

I have removed "examples" and "samples" from the "docs" category in the research. While they do not end up with a high enough frequency to warrant explicit inclusion in the standard, they are not prohibited.

Cf. https://github.com/php-pds/skeleton_research/blob/1.x/results/05-dirs.txt