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?