Mini Docs

[cuihtlauac]

Create a new kind of guides/tutorial documents. Basically, they have nothing special, except being shorter.

Motivation: Make topics easier to read, and easier to write. A bit like a blog post, but made to last and to be maintained. Longer than a tip, gotcha or faq entry, there's something to be understood, it's not just a cheat code, but it's a single idea, not a structured set of concepts.

Example Topics:

• What's the catch with the unit type
• Closures Demistyfied
• Curried vs Uncurried Functions
• Opam Switches: Why and How
• Pinning opam-repo

[christinerose]

I love this idea. It's usually more beneficial to have shorter documents than readers can consume relatively quickly. Long documents might be daunting to undertake, especially if it will take more than 20-30 minutes to go through it. Shorter sentences, headers, and more white space also seem to encourage people to read because it's easier to find what they're looking for and keep their place in the doc.

[christinerose]

After meeting with Sabine in Paris, we discussed the direction of the "Why OCaml" document for OCaml.org. It's currently a mixture of "About OCaml" and "Why OCaml." Let's consider making these two separate documents. With the history, top features, and growth of OCaml in the "About" page and a focus on exciting projects and the pain points OCaml addresses in "Why OCaml," making it the landing page.

If we put it on the landing page, it will be relatively short with a lot of white space for scanning rather than big blocks of text.

Let's also consider putting quotes from OCaml developers as why they chose/prefer/love OCaml, sprinkled throughout the site to break up text. It could be in a quote block or like a banner of sorts.