Glossary Structure Guidelines

glossary-structure-guidelines.md

• Do's

  • Structure glossary items (as applicable), i.e.:
    • Sentence 1:
      • What "<glossary_item_name>" is?
    • Sentence 2 (additional clarification):
      • Why "<glossary_item_name>" exists. What's the goal of having it?
      • How "<glossary_item_name>" makes a difference to achieve the why?
      • How "<glossary_item_name>" works?
      • What are the implications of "<glossary_item_name>"?
      • What are the restrictions imposed by "<glossary_item_name>"?
      • How "<glossary_item_name>" fits with other concepts?
  • Glossary items should be 1-3 line sentences that are clear, concise comprehensive review is going to be too costly for us.
    • Content writers must write docs based upon the code, rather than adopting general language that may have been used when concepts were explained during presentations (where context is all important), as comprehensive review is too costly.

• Don'ts

  • Avoid "braindumping" definitions that are just a copy'n'paste of numerous bullet points that aren't suitable for a glossary
  • Avoid terms that aren't actually used by are more suited to a FAQ to explanation
  • Avoid using bad grammar, unnecessarily long, incomprehensible or unclear paragraphs
  • Avoid useless definitions that just repeat the term in the definition
  • Avoid missing key points

• To consider

  • Associate terms with labels/tags within a hierarchy of categories (parent categories, reference categories) that reflect how a user would look for information