# An example for every OCaml package **URL:** \ **Category:** Ecosystem\ **Tags:** documentation, testing, announce\ **Created:** [July 10, 2025, 1:36pm UTC](https://discuss.ocaml.org/t/an-example-for-every-ocaml-package/16953 "2025-07-10T13:36:12Z")\ **Posts on this page:** 1\ **Showing post:** 1
**Author:** ![JohnWhitington](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/johnwhitington/32/1884_2.png) [@JohnWhitington](https://discuss.ocaml.org/u/JohnWhitington)\ **Post date:** [July 10, 2025, 1:36pm UTC](https://discuss.ocaml.org/t/an-example-for-every-ocaml-package/16953/1 "2025-07-10T13:36:13Z")
(One day, maybe). Wouldn’t it be nice if every OCaml package had examples as well as documentation? As part of a pilot programme funded by the OCaml Software Foundation, I’ve been looking into the feasibility of such an idea. What do we mean by examples, and what distinguishes them from documentation and from tests? **What an example is** - Examples are independent of the library they explain. They do not require the source of the library, or any built artefacts. - Examples are self-contained. They require only OCaml, a build system, and the library in question to be installed. - Examples are easy to build. They are built in a single command, and do not depend on environment. - Examples are easy to edit and play with. They are of a reasonable size, split into chunks, and are commented liberally. - Examples use standard techniques. Both in how the library is used, and in how the OCaml code is written. - Examples are open licensed. Users should be able to copy & paste code from the examples without care. **What an example is not** - Examples are not tests. Unlike tests, examples do not care about code coverage, cannot be automatically generated, and need not necessarily be tightly integrated into the source repository. - Examples are not in the API documentation. Examples need to be buildable, and separate from the API documentation. This is not to say that they might then not be automatically imported into the API documentation one day. - Examples need not be comprehensive. Better a small example than no example at all. So long as the basics of an API are introduced, the cliff is climbed and the API documentation should thereafter suffice. **Pilot project plan** The plan was to build small examples for about twenty packages, put together a place for them to live, and then try to upstream them. The examples’ home, prior to upstreaming, is the OCaml Nursery: > **[GitHub - johnwhitington/ocaml-nursery: Examples for OCaml libraries, prior to upstreaming](https://github.com/johnwhitington/ocaml-nursery)** > > Examples for OCaml libraries, prior to upstreaming Most of these little examples have been submitted to upstream - you may have noticed the pull requests on your repositories - with varying degrees of interest / success. **Opinions requested, please!** Are you interested in adding examples for your package or someone else’s package? To the nursery or to upstream? What do you think of the definition of example I gave above? Do you think examples should sit in a separate space like the nursery or be upstreamed or both? Opinions requested on all those topics, please! --- _[View the full topic](https://discuss.ocaml.org/t/an-example-for-every-ocaml-package/16953)._