I would never say my example is a good practice in a sense of moodle. But I would say, those code will help anyone to understand how moodle file system works! And how we can use the parameters to call a file in moodle way.

Unfortunately moodle documentation doesn't explain straight forward with easy example and that's why we have to spend time in forum with this kind of topics.

"There is no benefit to have lots of resources, if we don't know why/which/how to use them"

But the problem is that, as outlined above, your code does not demonstrate how to use parameters to call the file in a Moodle way - it shows how to bypass the Moodle way and retrieve files directly.

Yes, the documentation could be improved - I think it is great that Andy Normore started off the local/filemanager example as a demo of how to use the filemanager and access files within Moodle (I extended it and corrected some of the problems in my version here https://github.com/davosmith/filemanager ). Maybe when I have some spare time, I will look at updating the docs at http://docs.moodle.org/dev/File_API and http://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms or maybe just provide an extra page with a simple worked example in it. However, there are also lots of examples of how to use the files API inside Moodle core - take a look at the code for mod/resource for a reasonably straightforward example.