A system lexicon is a simple tool which can have a big impact on the success of the system. It aligns terminology among technical teams, the customer, subcontractors, support personnel, and end users. This creates shared understanding and improves consistency. Read on to learn how to implement this powerful tool on your program.
What it isn’t
A lexicon isn’t a glossary or abbreviation list, though it does resemble them to some extent.
A glossary defines terms and is useful for newcomers to a project. An abbreviation list, sometimes incorrectly called an acronym list1, serves as a quick reference.
A lexicon’s main purpose isn’t for learning or reference, it is to promote consistency in terms used and their meanings.
A consistent vocabulary
Precision of language, please!
The Giver by Lois Lowry2
When different teams in a project adopt different vocabulary, it leads to miscommunications, misunderstandings, confusing documentation, and inconsistent user interfaces. I have worked on projects where the same single piece of data was called very different things in the prime interface control document (ICD), subcontractor ICD, operator user interface (UI), and maintainer UI… At least the manuals matched the UIs; in other cases, I’ve seen manuals use different terms than the UIs!
A lexicon precludes and resolves these types of discrepancies. It includes all technical terms and phrases to be used across the project. Each entry specifies acceptable terms and abbreviations, notes alternative terms which should not be used, and distinguishes among terms which are often confused or used incorrectly.
The engineering review board vets and approves all entries, so there should be no question about their accuracy or authority.
An excerpt of a lexicon is presented below as an example.
Note the following features of lexicon entries:
- Terms are capitalized based on how they should be treated in written text. Many projects prefer to treat all components as proper nouns, and that’s okay. Either way, applying the preferred capitalization scheme here promotes consistency.
- Few of the items have an actual definition and only when necessary to help distinguish them from other terms. When terms are related or easily confused, the other terms are noted and hyperlinked (see “track”).
- Rather than a definition, most terms have some information to help clarify what they apply to (see “payload control unit” explaining that some related components aren’t included).
- Acceptable alternatives or abbreviations are listed with each term. Unacceptable alternatives or abbreviations are listed as well.
Creating a lexicon
As you can see, a lexicon is very straightforward but does take attention to detail. It also takes commitment from the program leadership to enforce its use. Ideally the lexicon is created early in the project, but it can be started at any point in the development.
Lexicon owner
The lexicon owner is someone with broad exposure to the various segments of the project who can ensure that terms are added and used. A well-placed human systems integrator is the ideal owner if available.
Collecting terms
The easy part is identifying and collecting the terms to be added. An established program will have a great deal of documents to comb through and likely a number of competing terms to sort out.
Early on in a program, the best place to start is legacy system manuals for operations and maintenance. Starting from established terms allows the program to be deliberate in choosing nomenclature, providing positive knowledge transfer and preventing negative knowledge transfer.
As the system evolves, new terms will be introduced and existing terms will evolve. Naturally, the lexicon is a living document. More on this later.
The lexicon owner is mindful of the scope of the document, which is limited to the system at hand. Acquisition terms are excluded with extreme prejudice. Nor can the document become a domain glossary. A good rule of thumb is to focus on terms which may be used in user-facing documentation or in project-level cross-team communications.
Terms are generally considered as they come up in the project, rather than being preemptively prescribed. Mining customer documents, requirements, and domain literature for terms is heavily discouraged.
The lexicon owner works with subject matter experts (SMEs) on the content of particular entries. The lexicon owner may make suggestions, particularly if the have a human factors role on the project, but usually defers to the SME. Ultimately, the engineering review board has final say on all content.
Leadership sponsor and review board
Implementing a cross-project tool requires cross-project authority and review. The lexicon has strong support from the chief engineer or similarly-placed leader to ensure its adoption. It also falls under the purview of the engineering review board and is subject to the program’s document/configuration management processes. In short, it is a rigorously developed and maintained tool which staff across the program rely on.
Hosting and sharing
The lexicon is accessible to the entire project team in a useful form. This varies by project but often takes the form of a Word document, Sharepoint site, or Confluence page. Naturally, access the latest version is important; emailed or offline copies should be avoided. To maximize utility, it should be easy to find and searchable
It is tempting to make the lexicon a section of the program’s style guide. However, technical staff may think that the style guide is only applicable to the user interfaces the system. The lexicon supports internal documentation just as effectively as external documentation. Therefore, it is usually an independent document which the style guide incorporates by reference. UI and documentation teams use the lexicon like any other technical personnel.
It is tempting to make the lexicon a section of the program’s style guide. However, technical staff may think that the style guide is only applicable to the user interfaces the system. The lexicon supports internal documentation just as effectively as external documentation. Therefore, it is usually an independent document which the style guide incorporates by reference. UI and documentation teams use the lexicon like any other technical personnel.
Tools
You might consider using the MS Word exclusion dictionary feature or a macro to efficiently evaluate documents. For configuration control and to avoid confusion among the engineering team, limit these tools to a small set of evaluators rather than sharing widely.
Using the lexicon
The lexicon is effective only when it is maintained, used, and enforced.
Using the lexicon is simple. Anyone authoring a document or UI looks up terms to be sure of the approved wording. Document reviews include a checklist step and designated for lexicon compliance reviewer. Use of incorrect terms is pointed out and adjudicated along with other document recommendations.
Identifying new terms and updates is everyone’s job in theory, but in practice it typically falls to the lexicon owner to notice and contact the relevant SME. Regardless of the source, change requests are addressed in the engineering review board. This gives everyone on the project the opportunity to provide input and ensures the lexicon entries are valuable.
All stakeholders benefit from the consistency provided by the lexicon. If your project doesn’t have one already, try it out and experience the benefits.
What has your experience been with a lexicon? Do you have suggestions and best practices to share? Are there any drawbacks? Let us know in the comments.
Footnotes:
- Acronyms, initialisms, and shortened words are all types of abbreviations. Most projects have a mix of these, so “abbreviation list” is usually the most accurate term.
- Ironic? I have no idea what you mean.