3.2 KiB
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 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 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 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 Layout and structure are nice, page themes seem flexible,
[Search: preview topic]
-
bevy engine
-
docusaurus