# Docs Initiative

UPDATE: for now, the zola static site generator is going to be used as a tentative docs platform.

This pages describes the _docs endeavor_, a rebuild of NoSQLBench docs based on feedback from users.

It is clear that the docs for NoSQLBench need to be better:

* Easier to find
* Easier to search
* Easier to read
* Easier to modify by contributors

While the previous doc site was intended to be part of a cohesive docs+sandbox experience, this has
come at the cost of a high barrier of entry for new users wishing to improve things.

## Selection Criteria

The docs system that replaces the current one must do the following:

- Allow for community members to easily modify the content with little friction.
- Render clean content, whether basic markup or syntax examples.
- Provide a visually appealing, no-clutter, highly readable theme out of the box.
- Allow for formatting patterns to be defined and re-used throughout.
- Be easy to integrate into the build, CI/CD.
- Provide a search index, preferably in-build and not externalized.
- Provide a useful hierarchic navigation structure.
- Allow for fenced code sections which are clean and syntax highlighted, with easy clipboard copy.
- Avoid bringing in kitchen-sink dependencies and whole ecosystems just to render.

To that end, several examples are listed for study.

## Inspiring Examples

These are doc sites that have examples of good docs. This list will be built out in more detail
as time allows.

- [Antora Docs](https://docs.antora.org/antora/2.3/install-and-run-quickstart/)
  Antora docs are rendered nicely, have a responsive layout with useful cues and
  details on the page, but the Antora system itself is overly complex to manage
  relative to other SSG systems,  based on reviews. [Search: preview]
- [Apache Groovy](http://groovy-lang.org/documentation.html)
  Visually, this site is simple and appealing. However, it is written in Groovy, which is not very
  approachable by most contributors as a documentation method. This is antithetical to the
  goals of the docs initiative. [Search: google]
- [Prometheus](https://prometheus.io/docs/prometheus/latest/querying/basics/)
  These docs have a nice layout and a clean structure. This site is generated by nanoc, which is
  a ruby SSG. Extension points seem to be very ruby-centric, with a thin layer of content helpers
  built-in. At cursory glance, this SSG is probably not sophisticated enough for some
  integrations needed without substantial coding. [Search: basic]
- [NetData](https://learn.netdata.cloud/)
  Layout and structure are nice, page themes seem flexible,

  [Search: preview topic]
- [Optimizely](https://developers.optimizely.com/x/solutions/javascript/reference/index.html)
- [Elastic Step by Step](https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/java-rest-high-search.html)
- [Javascript.info](https://javascript.info/strict-mode)
- [TiKV docs - explore the tabs](https://tikv.org/docs/3.0/concepts/overview/)
- [rocket](https://rocket.rs/v0.4/overview/)
- [stripe](https://stripe.com/docs/payments/integration-builder)
- [tokio.rs](https://tokio.rs/)
- [amazon ion](http://amzn.github.io/ion-docs/guides/cookbook.html)
- bevy engine
- docusaurus