User guide contributor guide

aburdenthehand commented 1 year ago

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 commented 1 year ago

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

aburdenthehand commented 1 year ago

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 commented 11 months ago

I would like to work on this

aburdenthehand commented 10 months ago

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

pragatisaikia commented 10 months ago

@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 commented 10 months ago

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

pragatisaikia commented 10 months ago

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

I think you can work on this

UncleWeeds commented 10 months ago

/assign

kubevirt-bot commented 7 months ago

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 commented 6 months ago

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 commented 5 months ago

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

/close

kubevirt-bot commented 5 months ago

@kubevirt-bot: Closing this issue.

In response to [this](https://github.com/kubevirt/user-guide/issues/701#issuecomment-2003855396): >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](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.

chuot803 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

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 commented 4 months ago

@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 commented 1 month ago

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 commented 1 week ago

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 / user-guide

User guide contributor guide #701