Proposal: Versioning of Documentation #2349

jaybatra26 · 2020-03-28T19:05:40Z

What this PR does:
Let's start a discussion about how to version documenation.
I have listed a few tools that can be used with their respective
pros and cons.

Which issue(s) this PR fixes:
Fixes #

Checklist

Tests updated
Documentation added
CHANGELOG.md updated - the order of entries should be [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX]

pracucci · 2020-03-30T07:56:34Z

docs/.vscode/settings.json

@@ -0,0 +1,6 @@
+{


Is this file introduced intentionally? I don't think should be commited.

pracucci · 2020-03-30T07:58:24Z

docs/proposals/version-documentation.md

+1. Version Documentation.
+2. Add or remove necessary and unnecessary data from it.
+3. Organize the documentation so that it's easily understandable.


I think we're trying to address too much in this proposal. We should get stick to our goal: having a way to version part of the documentation (the one which is expected to change version-by-version, like config file).

pracucci · 2020-03-30T08:02:30Z

docs/proposals/version-documentation.md

+The idea is to use a tool to organize current documentation. Prometheus uses netlify. 
+Rucio uses Sphinx. Other tools like Github Pages


I think the following section is focusing on the wrong problem. We don't want to change how the website is built or deployed (unless strictly required, but let's say we should try to avoid it as much as possible), while we should focus the discussion on:

Which pages do we want to version?

For which versions we want to add a new versioning? Major, minor or patch version? I would say we want versioning for minor version (ie. 1.0, 1.1, ...)

How do we manage the versioning at website build time? How do we build the config for the version 1.0, 1.1, ... over the time?

pracucci · 2020-03-30T08:02:42Z

docs/proposals/version-documentation.md

+
+## Problem
+
+In Cortex, documentation needs a lot of reordering. 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. 


What do you mean by "reordering" here?

pstibrany · 2020-04-01T09:08:02Z

docs/proposals/version-documentation.md

+4. Supports custom domains. 
+
+#### Cons
+1. Currently, there is no support for HTTPS for custom domains. It’s probably coming soon though.


HTTPS for custom domains works for some time now (I use it myself for at least a year)

pracucci · 2020-04-22T08:59:38Z

Thanos is also going to address the same (see thanos-io/thanos#2488). @jaybatra26 Are you still interested into working on this? Otherwise I guess we can close the proposal because stale.

jaybatra26 · 2020-04-22T10:40:32Z

@pracucci I am, lemme rewrite the proposal and come back to you in a few hours.

docs/proposals/version-documentation.md

Let's start a discussion about how to version documenation. I have listed a few tools that can be used with their respective pros and cons. Signed-off-by: Jay Batra <jaybatra73@gmail.com>

Updates the proposal as per discussion on slack. Signed-off-by: Jay Batra <jaybatra73@gmail.com>

Signed-off-by: Marco Pracucci <marco@pracucci.com>

pracucci

Thanks Jay! LGTM 🎉

FYI, I've just pushed a commit to fix the markdown layout and mention that the "running-cortex" URL path segment may change during implementation.

jaybatra26 · 2020-04-24T07:39:06Z

Thanks Jay! LGTM 🎉

FYI, I've just pushed a commit to fix the markdown layout and mention that the "running-cortex" URL path segment may change during implementation.

Thanks for the input @pracucci. I sincerely appreciate it.

Signed-off-by: Marco Pracucci <marco@pracucci.com>

bwplotka

Definitely we are doing the same thing here as thanos-io/thanos#2488

BTW We plan this to be Summer of Code project 🤗

Thanks @jaybatra26 for ping!

cc @pracucci

bwplotka · 2020-04-24T07:54:43Z

docs/proposals/version-documentation.md

+3. Include the master version and last 3 minor releases. Documentation defaults to the last minor release.
+
+
+## Proposed solution


Makes sense... but how? 😄

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).

@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

pstibrany · 2020-04-24T08:26:35Z

docs/proposals/version-documentation.md

+
+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.


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.

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.

pstibrany

LGTM, having quick access to old versions of documentation is useful at times.

A properly versioned documentation will help everyone to have a proper place to look for answers before flagging it in the community.

If only...

gouthamve

LGTM!

pracucci · 2020-04-28T13:49:25Z

I think enough time has passed to eventually let other maintainers look at this. Considering this is not a core feature (even if important for the user UX) let's consider the proposal approved and move on with the implementation @jaybatra26 🎉

jaybatra26 · 2020-04-29T06:57:04Z

Thanks, @pracucci . I have started working on it. :)

pull-request-size bot added the size/M label Mar 28, 2020

pracucci reviewed Mar 30, 2020

View reviewed changes

pstibrany reviewed Apr 1, 2020

View reviewed changes

jaybatra26 force-pushed the proposal branch 5 times, most recently from 455c298 to ac46fae Compare April 22, 2020 19:07

weeco reviewed Apr 22, 2020

View reviewed changes

docs/proposals/version-documentation.md Outdated Show resolved Hide resolved

Proposal: Versioning of Documentation

b7cc6d5

Let's start a discussion about how to version documenation. I have listed a few tools that can be used with their respective pros and cons. Signed-off-by: Jay Batra <jaybatra73@gmail.com>

jaybatra26 force-pushed the proposal branch from ac46fae to b7cc6d5 Compare April 23, 2020 06:35

Update Version Documentation Proposal

218bc2a

Updates the proposal as per discussion on slack. Signed-off-by: Jay Batra <jaybatra73@gmail.com>

jaybatra26 force-pushed the proposal branch from 331d8f0 to 218bc2a Compare April 23, 2020 19:43

Fixed markdown

b1cd594

Signed-off-by: Marco Pracucci <marco@pracucci.com>

pracucci approved these changes Apr 24, 2020

View reviewed changes

Cleaned white noise

6c96f69

Signed-off-by: Marco Pracucci <marco@pracucci.com>

bwplotka reviewed Apr 24, 2020

View reviewed changes

bwplotka mentioned this pull request Apr 24, 2020

Website documentation should be versioned. thanos-io/thanos#2488

Closed

pstibrany reviewed Apr 24, 2020

View reviewed changes

pstibrany approved these changes Apr 24, 2020

View reviewed changes

gouthamve approved these changes Apr 27, 2020

View reviewed changes

pracucci merged commit 3dfbe2f into cortexproject:master Apr 28, 2020

bwplotka mentioned this pull request Jun 8, 2020

Proposal: Building a versioning plugin for Thanos thanos-io/thanos#2554

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Proposal: Versioning of Documentation #2349

Proposal: Versioning of Documentation #2349

jaybatra26 commented Mar 28, 2020 •

edited by pracucci

Loading

pracucci Mar 30, 2020

pracucci Mar 30, 2020

pracucci Mar 30, 2020

pracucci Mar 30, 2020

pstibrany Apr 1, 2020

pracucci commented Apr 22, 2020

jaybatra26 commented Apr 22, 2020

pracucci left a comment

jaybatra26 commented Apr 24, 2020

bwplotka left a comment

bwplotka Apr 24, 2020

pracucci Apr 24, 2020

jaybatra26 Apr 24, 2020 •

edited

Loading

pstibrany Apr 24, 2020 •

edited

Loading

pracucci Apr 24, 2020

pstibrany left a comment

gouthamve left a comment

pracucci commented Apr 28, 2020

jaybatra26 commented Apr 29, 2020

		The idea is to use a tool to organize current documentation. Prometheus uses netlify.
		Rucio uses Sphinx. Other tools like Github Pages


		## Problem

		In Cortex, documentation needs a lot of reordering. 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.

		3. Include the master version and last 3 minor releases. Documentation defaults to the last minor release.


		## Proposed solution

Proposal: Versioning of Documentation #2349

Proposal: Versioning of Documentation #2349

Conversation

jaybatra26 commented Mar 28, 2020 • edited by pracucci Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pracucci commented Apr 22, 2020

jaybatra26 commented Apr 22, 2020

pracucci left a comment

Choose a reason for hiding this comment

jaybatra26 commented Apr 24, 2020

bwplotka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jaybatra26 Apr 24, 2020 • edited Loading

Choose a reason for hiding this comment

pstibrany Apr 24, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pstibrany left a comment

Choose a reason for hiding this comment

gouthamve left a comment

Choose a reason for hiding this comment

pracucci commented Apr 28, 2020

jaybatra26 commented Apr 29, 2020

jaybatra26 commented Mar 28, 2020 •

edited by pracucci

Loading

jaybatra26 Apr 24, 2020 •

edited

Loading

pstibrany Apr 24, 2020 •

edited

Loading