lone-writers-guide

Creating a Technical Glossary

You’re in a new situation:

• Start working on a glossary right away. You’re a new person with new eyes and ears: take advantage of this while it lasts.
• Look for glossaries that others have created.

• Terminology: what is industry standard that does not belong in our glossary? Or other constraints (3rd-party product’s terminology)

• You’re likely to be the person who finds discrepancies across teams or terms

• Hopefully part of the glossary can be customer-facing so that you can show that it’s worthwhile to be spending your time on this

• How you write the definitions in your glossary: write carefully so you know what knowledge to assume the audience has.

• Sources/SMEs for your glossary: YOU and your fresh eyes as you respond to practically anything you have contact with in your first days.

• Once you have a glossary made, use the glossary to control terminology (programmatically ideally, but also culturally). Get people to agree on terminology.

• Tease out internal versus external names

• Think about naming conventions for APIs

• Write definitions carefully, keeping in mind the audience’s level of familiarity with technology

• Aim for wide distribution: Sales, Marketing, Support, Professional or Managed Services, Dev, UX

• You want your glossary to be the “gold file” - the canonical document of record