Add some contributing notes and a style guide #183
Conversation
✅ Deploy Preview for graceful-kangaroo-3c9c10 ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
Signed-off-by: David Martin <[email protected]>
david-martin
force-pushed
the
style-guide
branch
from
89a2882 to
f0d2a7a
Compare
david-martin
changed the title
| ## Numbering in lists | ||
|
|
||
| Avoid the overuse of numbering. It allows for docs to be updated much easier in the future. |
There was a problem hiding this comment.
Is this only for the limitation of markdown. If it is more useful to have the sections number for the user, is it worth looking at restructuredtext (rst). In the rst adding .. sectnum :: to the top of the file will manage the numbering for all sections.
The main question what is best for the user, not what is easier for us.
There was a problem hiding this comment.
what is best for the user, not what is easier for us
Absolutely.
Switching from markdown is a non runner though as we're using mkdocs.
I'm only aware of 2 docs that used section numbering
- https://docs.kuadrant.io/0.11.0/kuadrant-operator/doc/user-guides/secure-protect-connect/
- https://docs.kuadrant.io/0.11.0/kuadrant-operator/doc/user-guides/secure-protect-connect-single-multi-cluster/
Both have been replaced by a non platform specific guide that doesn't have section numbering: https://docs.kuadrant.io/dev/kuadrant-operator/doc/user-guides/full-walkthrough/secure-protect-connect/
Perhaps that was the inspiration for this point?
Anyways, I think the wording on the guideline here is sufficient to make the writer question numbering, but not saying to not do it outright.
As with a lot of documentation, there can be element of subjective review, and whether or not something is overused can be argued. If something adds sufficient value, I don't see why it would be rejected.
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: david-martin, jasonmadigan The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
Signed-off-by: David Martin <[email protected]>
david-martin
force-pushed
the
style-guide
branch
from
43499a2 to
fcaf0a6
Compare
Co-authored-by: Thomas Maas <[email protected]> Signed-off-by: David Martin <[email protected]>
david-martin
force-pushed
the
style-guide
branch
from
a10e261 to
88719de
Compare
|
/lgtm |
Closes Kuadrant/kuadrant-operator#1118
The style guide content is a combination of some conversations on a different channel and some of the guidelines from https://kubernetes.io/docs/contribute/style/style-guide/