doc: add todos for new structure

[emillon]

This PR adds todo notes to finish migrating to a new structure for our documentation.

It is based on the Diátaxis framework. The core idea is to organize documentation based on what the user is after when reading it. 4 categories emerge:

• tutorials ("can you teach me how to...")
• how-to guides ("how do I...")
• reference guide ("what is...")
• explanations ("why...")

An example of docs where this has been used is the gatsby docs.

Our existing docs have a lot of good content in it but it is difficult to find because these concerns are mixed in the various documentation pages.

For example, all these aspects tend to be grouped together in a single page dedicated to a particular feature. But a reader rarely needs to refer to every aspect of the docs for that feature.

We also have some pages ("concepts" and "advanced topics") that are really several pages concatenated together with no strong unifying theme.

This shows how to go to both a desired "complete" state (see https://diataxis.fr/how-to-use-diataxis/#complete-not-finished).

[emillon]

cc @Alizter @rikusilvola @tmattio - this is the docs change we were discussing before.
You can see the preview here (I added notes on top of every page).

[bobot]

That's great! I like it very much. I would propose that part of the description of this MR goes to a Readme.md in order to precise what goes where.

Just the term Conceptual Guides seems strange, and this section answers only why it is done like that? not also how it is done under-the-hood?

[emillon]

Just the term Conceptual Guides seems strange, and this section answers only why it is done like that? not also how it is done under-the-hood?

That's a good point. The specific name is up to discussion, and I agree that this should probably contain both kinds of contents. We can start with Explanations or something like that.

[Alizter]

Does "reference guides" make sense as a title? Perhaps just "reference" is clear enough?

[emillon]

Does "reference guides" make sense as a title? Perhaps just "reference" is clear enough?

Yes, I think that it would work too.

[emillon]

Here's the new content that was suggested in this PR:

• Glossary: Extracted from :doc:overview.
• Quick Start: This document is a sped-up guide for more advanced developers. Points to dune build, dune runtest, and where to look for next steps (other guides, the help, places to ask for help).
• Developing with dune: You just cloned a repository that uses dune. What can you do? This explains dune build, dune runtest, and tasks like adding a dependency.
• From zero to opam: This guide is for authors of OCaml library. It walks the reader from an empty directory, to a tested library that is ready to be published on opam-repository. It explains project structure, shows a couple approaches for testing, and interaction with the various required tools.
• Changing compilation flags: Something that walks through the question: "I want to change some compilation flags, for example to ignore a warning. What do I change?". This shows some possibilities: at the stanza level, (env), etc.
• Testing an executable: Recycle the howto part of :ref:cram-tests: start from a project that defines a ls executable and show how to add cram tests for it and the associated workflow.
• Making a software bill of materials: Problem: we're making an end executable (for example an API server). We want to compute the list of libraries that are linked into it. This guide explains how to do this using dune-build-info.
• Setting up code coverage: Problem: we have a medium-sized project and we want to see how well it is covered by tests. We use bisect_ppx and the instrumentation API to select which items (libraries, executables) to instrument and generate a HTML coverage report.
• Stanzas: The existing contents of :doc:/dune-files, formatted using the new dune domain.
• Variables: Recycle contents of :doc:../concepts/variables.
• Files: What files dune looks for: dune, dune-project, dune-workspace, config. Pointers to things like alternative file names, :include, (include) and stanzas for each file type in stanzas.
• Dune libraries: A list of all the libraries that dune ships, with pointers to their API documentation.
• How configurator reads C constants: Recycle this blog post <https://dune.build/blog/configurator-constants/>_.

[emillon]

I worked on that PR to make it into a mergeable state:

• notes have been transformed into TODO(diataxis) comments that don't show up in the output
• new content has been moved to a checklist in this issue

So now that we agree on the project, I think we can integrate the TODOs in the documents like CRs in the rest of the codebase.

[emillon]

Since this is now just TODOs as lightweight tickets, I'm merging this.