Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: Versioning of Documentation #2349

Merged
merged 4 commits into from
Apr 28, 2020
Merged

Proposal: Versioning of Documentation #2349

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b7cc6d5
Proposal: Versioning of Documentation
jaybatra26 Apr 22, 2020
218bc2a
Update Version Documentation Proposal
jaybatra26 Apr 23, 2020
b1cd594
Fixed markdown
pracucci Apr 24, 2020
6c96f69
Cleaned white noise
pracucci Apr 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions docs/proposals/version-documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
title: "Documentation Versioning"
linkTitle: "Documentation Versioning"
weight: 1
slug: documentation-versioning
---

- Author: [Jay Batra](https://github.com/jaybatra26)
- Date: March 2020
- Status: proposal

## Problem

In Cortex, currently, we are missing versioning of documentation. The idea is to have version documentation just like Prometheus.[`Prometheus`](https://prometheus.io/docs/introduction/overview/). Documentation is the main source of information for current contributors and first-timers. A properly versioned documentation will help everyone to have a proper place to look for answers before flagging it in the community.

In this proposal, we want to solve this. In particular, we want to:

1. Version specific pages of the documentation
2. Include links to change version (the version must be in the URL)
3. Include the master version and last 3 minor releases. Documentation defaults to the last minor release.
Copy link
Contributor

@pstibrany pstibrany Apr 24, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not keep docs for all released minor versions? I have occasionally found it useful to be able to find very old (10-15 years) documentation for some projects, but if cost (in terms of maintainance, work, ...) is prohibitive, then let's not do that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good feedback. Given the fast pace of Cortex and that we just cut the first stable release, I was wondering if it's healthy to keep the doc for very old versions, considering we want people to use recent versions. But I don't feel strong about this, and at the end the number of versions to keep will just be a configuration option in the website generation.



## Proposed solution
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense... but how? 😄

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The goal of this proposal is primarily to get consensus about which pages should be versioned and how it should from the user-perspective. We decided that implementation details will be discussed deeper during the implementation phase (so that me and Jay can get a faster feedback loop, once we got consensus about versioning doc).

Copy link
Contributor Author

@jaybatra26 jaybatra26 Apr 24, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bwplotka Currently we use Docsy theme of HUGO. It allows versioning.
This is the gist of where we can start with.
https://www.docsy.dev/docs/adding-content/versioning/#adding-a-version-drop-down-menu


Currently, the documentation is residing under the docs/ folder of cortexproject/cortex. It is built by Hugo using the theme [`docsy`](https://www.docsy.dev). It will have a proper [`drop-down menu`](https://www.docsy.dev/docs/adding-content/versioning/#adding-a-version-drop-down-menu) which will enable proper versioning. It has a section [`params.version`](https://www.docsy.dev/docs/adding-content/versioning/#adding-a-version-drop-down-menu) in config.toml which will allow us to map URLs with proper versions. We will have to change all the occurrences of older doc links with new links. We will keep `master` version with 3 latest `release` versions. Each release is a minor version expressed as `1.x`. The document would default to latest minor version.

From the current doc, the following paths (and all their subpages) should be versioned for now:

1. https://cortexmetrics.io/docs/apis/
2. https://cortexmetrics.io/docs/configuration/ (moving v1.x Guarantees outside of the tree, because these shouldn't be versioned)

The above should be versioned under a single URL path (`/docs/running-cortex/` in the following example, but final prefix is still to be decided).

### Example:

For `master` version we would be able to use the above links via the following path

```
/docs/running-cortex/master/configuration/
/docs/running-cortex/master/api/
```

And for a minor version like `1.x`:

```
/docs/running-cortex/1.0/configuration/
/docs/running-cortex/1.0/apis/
```

we'll have versioned documentation only under the /docs/running-cortex/ prefix and, as a starting point, all versioned pages should go there.