Website: AI: Create mini style guide.
Create a mini style guide for how we should write and implement glossary snippets.
chenopis
All 8 comments
@abiogenesis-now @heidecke
chenopis
on 11 Aug 2017
@Bradamant3 Where should we put this? If I create a template file that people can clone and drop in content, i.e. /_includes/glossary/_snippet-example.md, should we maybe just put it in there in a commented out section so that people can refer to it without having to look at a different file?
chenopis
on 11 Aug 2017
I've stubbed this out. Examples are the next step, but would like feedback first before I develop them (I think examples are the best way to provide more guidance, but if y'all think we should provide more explanatory text, just let me know).
Draft:
Minimum viable snippet:
short-description. Required. One or two lines that provide a minimum definition. Do not repeat the term. Prefer fragments. Model after tooltips.
long-description. Optional. Longer additional text to appear after (in conjunction with) short description. Provide where the short description is not sufficient as the intro paragraph to a topic. Write complete but concise sentences.
Bradamant3
on 11 Aug 2017
Woops, +100 to including in an example template, not a separate file. Hence review here :-)
Bradamant3
on 11 Aug 2017
Seems reasonable to me!
abiogenesis-now
on 11 Aug 2017
I've added the draft to /_includes/glossary/_glossary-template.md. Feel free to make additional changes there.
chenopis
on 14 Aug 2017
@Bradamant3 Do you want to keep this open, or should I close this now that we have something committed to the repo?
chenopis
on 14 Aug 2017
This was addressed by https://github.com/kubernetes/kubernetes.github.io/pull/4865 in _includes/templates/glossary/README.md.
chenopis
on 28 Aug 2017
Related issues
neha-viswanathan
·
3Comments
Karunamon
·
3Comments
BrunoQuaresma
·
4Comments
adityamandhare
·
3Comments
sftim
·
4Comments
Most helpful comment
I've stubbed this out. Examples are the next step, but would like feedback first before I develop them (I think examples are the best way to provide more guidance, but if y'all think we should provide more explanatory text, just let me know).
Draft:
Minimum viable snippet:
short-description. Required. One or two lines that provide a minimum definition. Do not repeat the term. Prefer fragments. Model after tooltips.
long-description. Optional. Longer additional text to appear after (in conjunction with) short description. Provide where the short description is not sufficient as the intro paragraph to a topic. Write complete but concise sentences.