operator-framework
Add documentation style guide
To increase consistency, lets document decisions we make.
- For internal links, use relative links rather than absolute paths
- For example commands, do we use
$ operator-sdk initoroperator-sdk init - For all links, prefer
[text][link-name]to[text](https://link) - Verb forms in headers (e.g. present participle "Creating a project" vs. imperative "Create a project")
Feel free to add others.
Issues go stale after 90d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle stale
Issues go stale after 90d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle stale
Stale issues rot after 30d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle rotten /remove-lifecycle stale
Perhaps the SDK site could also have a style guide page similar to upstream k8s doc. And we could see if any established conventions we'd like to leverage too.
Issues go stale after 90d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle stale
Stale issues rot after 30d of inactivity.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.
Exclude this issue from closing by commenting /lifecycle frozen.
If this issue is safe to close now please do so with /close.
/lifecycle rotten /remove-lifecycle stale
Rotten issues close after 30d of inactivity.
Reopen the issue by commenting /reopen.
Mark the issue as fresh by commenting /remove-lifecycle rotten.
Exclude this issue from closing again by commenting /lifecycle frozen.
/close
@openshift-bot: Closing this issue.
In response to this:
Rotten issues close after 30d of inactivity.
Reopen the issue by commenting
/reopen. Mark the issue as fresh by commenting/remove-lifecycle rotten. Exclude this issue from closing again by commenting/lifecycle frozen./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.
![openshift-ci[bot] avatar](https://avatars.githubusercontent.com/in/91280?v=4 "Published by a pub.dev verified publisher"){kind=small}
I'll bring this up at the chairs meeting, it would be nice to share this style guide with OLM, so it might make sense in the community repo.
Hi @asmacdo,
In the past when we discussed this topic and we spoke about adopting the Kubernetes style guide. I think we should move with this idea instead of re-invent the wheel see: https://kubernetes.io/docs/contribute/style/style-guide/.
Also, SDK takes a lot of advantage of the Kubebuilder docs which follows this style so would be nice (ihmo) if we try to keep all under kubernetes-sig and if possible OF org very similar so that we can receive contributions easily from those who contribute with kubernetes-sig.
About the description of this task:
For internal links, use relative links rather than absolute paths
That is a statement for all that is possible already right? Otherwise, we do not have the docs properly versioned. It must be a rule for us and I understand that it is already. It is something that we discussed in the past and does not seems to make sense to me we do not use relative paths as much as possible.
For example commands, do we use $ operator-sdk init or operator-sdk init For all links, prefer [text][link-name] to text
I understand that is a rule for us already. You can see that 90% of the scenarios alias is used and the links are at the bottom of the pages. The reason here is maintainability.
Verb forms in headers (e.g. present participle "Creating a project" vs. imperative "Create a project")
For this one, I think we need to move forward with how K8s docs are in these docs. They have a huge team just to work on that and I think would be beneficial for us just to adopt the same practices.
c/c @awgreene
I completely agree that we should use the k8s style guide, but I also advocate that we should have our own to supplement.
Our supplement should not ~reinvent the wheel (idiom lol)~ waste time redefining accepted standards, it should only include extra style decisions that are not mentioned in the k8s style guide. (Operator vs operator is another example).
It may also be necessary to override k8s style guide decisions (someday? idk any examples). We are very behind in our hugo/docsy version, and k8s may mention features we don't have.
For internal links, use relative links rather than absolute paths
That is a statement for all that is possible already right? Otherwise, we do not have the docs properly versioned. It must be a rule for us and I understand that it is already. It is something that we discussed in the past and does not seems to make sense to me we do not use relative paths as much as possible.
Yes. Even though this rule can be derived, my intention is to make it easy for new contributors, and this is a common mistake. If we make a decision, let's write it down so the newbies don't have to guess what the rules are.
For example commands, do we use $ operator-sdk init or operator-sdk init For all links, prefer [text][link-name] to text
I understand that is a rule for us already. You can see that 90% of the scenarios alias is used and the links are at the bottom of the pages. The reason here is maintainability.
For this one, we include $, but k8s does not. I don't have a strong opinion here, just pointing out that this is one place we have deviated. We can either embrace and document that choice or fall back to the k8s document and remove the $s.
Hi @asmacdo,
For this one, we include $, but k8s does not.
It also was discussed before we should not use $ as well. See that we have NOT them in the quick start: https://sdk.operatorframework.io/docs/building-operators/ansible/quickstart/
Why we should not use $? it makes hard for users copy and paste and run the commands. However, yes we have docs that have $ because they wrote before
I completely agree that we should use the k8s style guide, but I also advocate that we should have our own to supplement.
What need do we have now that doc/definition does not attend or missing and we need to have our extra rules? This one described above? If so, I understand that all raised here were discussed and conveyed was made in the past. Then, I agree with you 100% that it should be in a place so then we would not need to speak about that now :-)
Sugestion
In this way, wdyt about: we add these 3/4 rules/tips to contribute with the docs here: https://sdk.operatorframework.io/docs/contribution-guidelines/documentation/ and link the k8s guidelines to sort out this matter? Something like:
The guidelines adopted to contribute to the docs are the same ones defined for the Kubernetes doc. For further information see:
On top of that, we would like to kindly highlight attention for some requirements
- Use relative path as always as possible (i.e ...). Note that the docs are versioned by release.
- Do not use $ because it makes it harder for users to copy and paste the commands
- Use the alias for the links and keep the alias definition at the bottom of the page, i.e