Proposal: move things like API conventions back to k/k or somewhere more logical

[thockin]

Describe the issue

There's a discussion in sig-net for where to put docs related to "how to write a service proxy". This is highly technical, and is coupled to core kubernetes APIs. Putting it in k/community/contributors/devel feels wrong.

We have things like the API conventions there, already, and they are hard to find. Yes, API conventions apply to more than just k/k, but k/k feels like a better home, to me.

What if we moved those docs to k/k/docs/dev/.. ?

@liggitt @danwinship @sftim

[sftim]

I'd put these conventions within https://k8s.dev/docs/

I don't mind where the source Markdown lives.

[thockin]

Whence that content today?

[thockin]

The reason I like k/k is that I can update docs and code together :)

[youngnick]

I would love for the API conventions and API changes docs to be somewhere that's easier to find, I'm constantly sending them to people who are building CRDs.

k8s.dev/docs seems like it would be way better than the current location to me.

[palnabarun]

/sig architecture
/sig contributor-experience

[palnabarun]

k8s.dev/docs seems like it would be way better than the current location to me.

Wherever the docs live, AFAIK we can link the docs to the contributor-website easily. There is a mechanism to pull in markdown content from other repos.

[mrbobbytables]

Wherever the docs live, AFAIK we can link the docs to the contributor-website easily. There is a mechanism to pull in markdown content from other repos.

The mechanism is a little jank...its some terrible bash I wrote awhile ago, but somehow still seems to work. As long as the docs follow the style guide, they should render correctly when pulled in by k8s.dev.

The benefit is that it is actually discoverable vs just in GH, but you can still version it and manage it in place alongside k8s

[danwinship]

So...

1. Everyone agrees it would be good to put more stuff in https://k8s.dev/docs/
2. We can pull content to there from arbitrary repos, though maybe this process can use some love (and if we're going to pull content from a bunch of places then probably every page should have an explicit link back to its source so people can find it when they need to edit it).
3. No one has objected to the idea of moving k/community/contributors/devel to k/k/docs/devel... should we do that? Should that wait until after the content has been published to k8s.dev?
4. Even if we didn't move that (or didn't move it right away) we might still start putting other technical docs in k/k now (eg, the service proxy doc) and publishing them to k8s.dev...?

[mrbobbytables]

3. No one has objected to the idea of moving k/community/contributors/devel to k/k/docs/devel... should we do that?

k/community/devl has a bit more in it with things that probably don't belong in k/k/docs/devel, but we could move the relevant things there.

Should that wait until after the content has been published to k8s.dev?

The "blocker" for publishing to k8s.dev is doing a small audit to make sure it conforms with the style guide (hugo + the script that pulls in data from other sources is more particular about this stuff than github) and adding the right metadata etc at the top of the doc - here is an example:

community/contributors/guide/coding-conventions.md

Lines 1 to 8 in 78d4703

	---
	title: "Coding Conventions"
	weight: 8
	description: |
	This document outlines a collection of guidelines, style suggestions, and tips
	for writing code in the different programming languages used throughout the
	Kubernetes project.
	---

One other thought - This pivots slightly to the idea of storing them alongside k/k - but one option would be to make k8s.dev the singular source of truth for everything.

[thockin]

This fell off the bottom of my email.

On one hand, API conventions and similar things are not REALLY specific to k/k. On the other hand, it seems pretty widely agreed that the current home is hard to find and reference.

I don't object to publishing through k8s.dev, but it would be nice if they were easily readable in plain text, too.

The service-proxy doc seems well appropriate for k/k/docs/ but what sort of structure do we want there?

[sftim]

I don't object to publishing through k8s.dev, but it would be nice if they were easily readable in plain text, too.

Markdown is pretty close, so we can likely find a good compromise.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[thockin]

/remove-lifecycle rotten

[danwinship]

ok, I filed kubernetes/kubernetes#124872 to try to get this going...

[thockin]

For those following:

Duplicating some from kubernetes/kubernetes#124872

We need more technical docs and we need to keep them more up to date. IMO, these are not "glossy", end-user facing docs that need fancy formatting. They are (IMO) text docs (or simple markdown), which are aimed at implementors. I'm not AGAINST fancy formatting, but I don't want to waste time on it.

Today the answer for such docs would be either https://git.k8s.io/community/contributors/devel/sig-xyz or https://git.k8s.io/community/sig-xyz - neither is terrible, but really "community" is not the repo wherein I would expect to find technical docs.

So, to me it makes sense to stick them in k/k/docs/..., but I would be fine with something like k/dev-docs/..., and if pressed I could just concede one of the above.

[sftim]

https://github.com/kubernetes/contributor-site/? “simple Markdown” is fine there; no expectation of following the SIG Docs style guide, of making text localization friendly, etc.

It's also where we should be telling contributors to look: https://k8s.dev/docs/

[sftim]

If someone wants to do k/k and a Prow job or GitHub Action so that code and docs change together, that's OK. But if we tell people “look at https://k8s.dev/docs/” then that's much easier than “look at https://k8s.dev/docs/, and also here, and also there, and…”.

It needs to be easy, because contributors also have the option of deciding it's not worth the effort to keep looking.

[danwinship]

I thought discussion above (#7421 (comment)) implied that k8s.dev could pull documentation from multiple repos? (Or maybe it implied there was an existing mechanism to sync content from other repos into kubernetes/contributor-site? I guess it wasn't clear...) @palnabarun @mrbobbytables ?

[mrbobbytables]

I thought discussion above (#7421 (comment)) implied that k8s.dev could pull documentation from multiple repos? (Or maybe it implied there was an existing mechanism to sync content from other repos into kubernetes/contributor-site? I guess it wasn't clear...) @palnabarun @mrbobbytables ?

It can pull from multiple repos, its a bit jank and could use an update (rewrite in something other than bash >_>) but it works. Mostly just need to make sure they have the right header in there.