Initial roadmap

Part of ocaml#210.

[skip ci]

CONTRIBUTING.md

@@ -6,7 +6,6 @@ Please ask any questions you have about odoc, [open any issues][issues],
 If you'd like specifically to work on the code of odoc, we hope that you will
 find the information in this file helpful.
 
-[issues]: https://github.com/ocaml/odoc/issues
 [contact]: https://github.com/ocaml/odoc#contact
 
 <br/>
@@ -18,8 +17,13 @@ find the information in this file helpful.
   - [Debug prints](#Debug_prints)
   - [Expect tests](#Expect_tests)
   - [Coverage analysis](#Coverage_analysis)
-- [Roadmap](#Roadmap)
 - [Project structure](#Project_structure)
+- [Roadmap](#Roadmap)
+  - [Project status](#Project_status)
+  - [General direction](#General_direction)
+  - [Not supported in the near term](#Not_supported_in_the_near_term)
+  - [Releases](#Releases)
+  - [Issue organization](#Issue_organization)
 
 <br/>
 
@@ -201,18 +205,6 @@ writing new tests, and want to know what they are actually touching. To use it,
 
 <br/>
 
-<a id="Roadmap"></a>
-## Roadmap
-
-1. We use [GitHub projects][projects] for grouping issues into overall topics. If you'd like to find an issue that isn't being worked on, try picking one up from the *To do* column of any of the projects!
-
-2. We use [milestones][milestones] to keep track of issues that we want to finish before the next release.
-
-[projects]: https://github.com/ocaml/odoc/projects
-[milestones]: https://github.com/ocaml/odoc/milestones
-
-<br/>
-
 <a id="Project_structure"></a>
 ## Project structure
 
@@ -307,3 +299,95 @@ rot, and we haven't gotten around to restoring yet.
 [test-print]: https://github.com/ocaml/odoc/tree/master/test/print
 [test-dune]: https://github.com/ocaml/odoc/tree/master/test/dune
 [test-inactive]: https://github.com/ocaml/odoc/tree/master/test/inactive
+
+<br/>
+
+<a id="Roadmap"></a>
+## Roadmap
+
+Everything here is subject to your input. Please discuss the roadmap in [#210, the roadmap issue][roadmap-issue].
+
+[roadmap-issue]: https://github.com/ocaml/odoc/issues/210
+
+<br/>
+
+<a id="Project_status"></a>
+### Project status
+
+odoc is currently in **beta**. We aim for odoc to be good for diverse use cases
+*in the future*, but for now we are focused on fast development satisfying
+limited goals.
+
+<br/>
+
+<a id="General_direction"></a>
+### General direction
+
+The current goal of odoc is to become more useful for single projects. This
+includes:
+
+- **Quality of output** &mdash; Emitting good HTML, with usability features such
+as whole-project search, etc. See the
+[**Usability project**][usability-project].
+- **Build integration** &mdash; Good interop with Dune for the OCaml and Reason
+native ecosystems, and BuckleScript for the Reason/BuckleScript ecosystem. See
+the [**Reason and BuckleScript project**][re-bs-project]. The Dune integration
+is handled in the [Dune repo][dune].
+
+Eventually, we want to start generating centralized docs for the entire OCaml
+(and/or Reason) ecosystem, and hosting them at docs.ocaml.org. We are not
+focused on this right now.
+
+[usability-project]: https://github.com/ocaml/odoc/projects/1
+[re-bs-project]: https://github.com/ocaml/odoc/projects/2
+[dune]: https://github.com/ocaml/dune
+
+<br/>
+
+<a id="Not_supported_in_the_near_term"></a>
+### Not supported in the near term
+
+We'd like to support most of these things *eventually*, but the code base is
+not ready for them, or we don't have enough time to implement them in the near
+term. They are:
+
+- The ability to emit HTML fragments.
+- Compatibility with odig or other tools that drive odoc, besides the build
+  systems Dune and bsb.
+- Stable markup at the HTML level.
+- Explicit custom themes.
+
+<br/>
+
+<a id="Releases"></a>
+### Releases
+
+We plan to release features fairly regularly (perhaps at most every 1-3 months).
+
+odoc uses [**milestones**][milestones] for planned releases, with lists of
+outstanding issues that they are to include. Note that many issues that have
+already been resolved might not have been assigned to a milestone, but will
+still be released.
+
+If you'd like an issue to be added, please comment in it!
+
+<br/>
+
+<a id="Issue_organization"></a>
+### Issue organization
+
+- [**Milestones**][milestones] keep track of outstanding issues that definitely
+  need to be done for a certain release.
+- [**Projects**][projects] are long-term categories of issues. Visit each one,
+  and you can see progress at a glance.
+- We use several **labels** to give developers an idea of what each issue
+  involves at a glance. See the [list of labels][labels], but they are really
+  meant just to appear in the [issues list][issues] and be clickable.
+- The [**good first issue**][easy-issues] label is meant to help new
+  contributors find something they can get started with.
+
+[milestones]: https://github.com/ocaml/odoc/milestones
+[projects]: https://github.com/ocaml/odoc/projects
+[labels]: https://github.com/ocaml/odoc/labels
+[issues]: https://github.com/ocaml/odoc/issues
+[easy-issues]: https://github.com/ocaml/odoc/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22

README.md

@@ -137,9 +137,11 @@ Please also don't hesitate to [open an issue][issues].
 Any [question asked](#contact), [issue opened][issues], feedback offered, is a
 contribution to odoc, and the project and all its users are thankful :) If
 you'd like to contribute code specifically, you may find the guide in
-[`CONTRIBUTING.md`][contributing.md] helpful. If anything is missing from it,
-please don't hesitate to [reach out](#contact) for help.
+[`CONTRIBUTING.md`][contributing.md] helpful. Also see the [roadmap][roadmap]
+there. If anything is missing from it, please don't hesitate to
+[reach out](#contact).
 
 [discourse]: https://discuss.ocaml.org/c/eco
 [issues]: https://github.com/ocaml/odoc/issues/new
 [contributing.md]: https://github.com/ocaml/odoc/blob/master/CONTRIBUTING.md#readme
+[roadmap]: https://github.com/ocaml/odoc/blob/master/CONTRIBUTING.md#Roadmap