CreateTechnicalGlossary

<!-- https://docs.google.com/document/d/1BcVN-04QbKYrfLLUeRfvjL-9w5jXgAmLX9wIcASV5q8/edit# -->

*****************************
Creating a Technical Glossary
*****************************

=================================================================
How to swim in the deep water - A lone writer’s guide to survival
=================================================================

Starting notes:
---------------

* Create a Technical Glossary. How to go about gathering up all the product-specific / company-specific nouns and verbs, define them in a Technical Glossary, then get (at least) engineering, support, marketing and sales to agree on the definitions. This provides the writer, the company, and the customers with standardized technical terms.
* Is there a need to document industry standard terms?


Hack-a-thon content:
--------------------

You’re in a new situation:
* Start working on a glossary right away. As new person, your eyes and ears are new.
* 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 :)

Once you have a glossary made, use the glossary to *control* terminology (programmatically ideally, but also culturally)

Political aspect: getting people to agree on terminology

Tease out internal versus external names

Related topic: naming convention for APIs

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

sources/SMEs for your glossary: YOU and your fresh eyes
practically anything you have contact with in your first days

Wide distribution: Sales, Marketing, Support, ProfSvces, Dev, UX

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