System lexicons and why your project needs one

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.

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 list, 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.

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:

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.

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.

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.

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.

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.

Related posts:

He escuchado incontables pitches para recibir inversión. Como analista de un venture capital y apoyando a redes de ángeles inversionistas, he escuchado pitches de startups de toda la república…

Based on the Ambrose and Dirksen models/theories we discussed, what ideas do you have for helping your learners acquire the necessary skills to gain mastery? What role might form play in your ideas…

My later teens were about Harry Potter. They were about finding my Hogwarts and finding my magical story. When it ended, I felt there would be nothing that could fill the void. But then came the…