User guide contributor guide

[aburdenthehand]

It would be good to update our contributor guide for KubeVirt docs to capture some of the conventions. The current guidelines are very high level, and the repo readme focuses on test builds - all good stuff, but some lower level guidance for things like basic structure, style, and conventions like version support and when to deprecate content etc would be useful.

Links:
https://kubevirt.io/user-guide/contributing/ (currently an issue already open about the multiple redirects to get to this page: #659 )
https://github.com/kubevirt/user-guide

[pragatisaikia]

May I know exactly what changes are we suppose to make to which files.

[aburdenthehand]

Hi @pragatisaikia - thank you for your enthusiasm and patience!
I think we will want to create a new file, and I think the best place for it will be in the root directory of the user-guide repo.
We can call it 'docs-guidelines.md'

To start with, we can copy a couple of the relevant points from the blog guidelines, namely:

- Follow [Kramdown Quick Reference](https://kramdown.gettalong.org/quickref.html) for syntax reference
- Split the contents in sections using the different levels of headers that Markdown offers
  - Keep in mind that once rendered, the title you set in the Front Matter data will use `H1`, so start your sections from `H2`
- [Code blocks](https://kramdown.gettalong.org/syntax.html#code-blocks), use them for:
  - code snippets
  - file contents
  - console commands
  - ...
  - Use the proper tag to let the renderer what type of contents your including in the block for syntax highlighting
 - Don't include a command prompt in console commands, to simplify copy/paste.

We can postpone the version support for the moment as it is still being discussed.
Thanks!

[UncleWeeds]

I would like to work on this

[aburdenthehand]

@pragatisaikia - are you still interested in working on this? If not, I will assign @UncleWeeds

[pragatisaikia]

@pragatisaikia - are you still interested in working on this? If not, I will assign @UncleWeeds

I'm looking into it. If not resolved, I'll mention asap.

[UncleWeeds]

@aburdenthehand it's been a while can I start working on this

[pragatisaikia]

@aburdenthehand it's been a while can I start working on this

I think you can work on this

[UncleWeeds]

/assign

[kubevirt-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

/lifecycle stale

[kubevirt-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

/lifecycle rotten

[kubevirt-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

/close

[kubevirt-bot]

@kubevirt-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[chuot803]

Hi! My group and I from UT Austin are interested on working on this :) I was wondering what work has already been done towards this issue and what else we would need to add. Thanks!

[aburdenthehand]

Hello @chuot803 - I'm not aware of any movement on this. From my point of view you are very welcome to work on this.
@UncleWeeds ?

[tbunch1]

Hi, I'm working with Lindsey. You mentioned adding information about when to deprecate content. When should that be? Or where can I find information on things like that?

[aburdenthehand]

@tbunch1 - Great question. We can use our support matrix to guide us here.
Once it passes 3 K8s versions out of date (ie, if it's no longer present on our matrix at all) then we can safely remove it. This gives folks ~1 year out of support.

[kubevirt-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

/lifecycle stale

[kubevirt-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

/lifecycle rotten

[kubevirt-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

/close

[kubevirt-bot]

@kubevirt-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.