Service
APIs, microservices, applications, and other software systems. Services often have dependencies, owners, and documentation.
Landmarks
Landmarks are the universal points of interest in your organization. They represent anything worth knowing about: services, projects, resources, events, documentation, vendors, and more.
What Is a Landmark?
Section titled “What Is a Landmark?”A landmark is a flexible entity type that can represent almost anything in your organizational ecosystem. Instead of creating separate entity types for services, projects, and resources, Legend uses landmarks with categories to distinguish between them.
Think of landmarks as the “what” in your organization. They are the things people work on, depend on, maintain, or reference. Every landmark has:
- A name and description
- A category that defines its type
- An icon for visual identification
- Optional links to external resources
- Optional documentation files
- An owner (team or person)
- Tags for organization and filtering
Landmark Categories
Section titled “Landmark Categories”Categories distinguish between different types of landmarks. Legend provides six default categories, and administrators can create custom categories to match your organization’s needs.
Resource
Databases, clusters, devices, infrastructure components, and other shared resources. Resources are often depended upon by services.
Project
Initiatives, OKRs, epics, and other organized work. Projects have timelines, teams, and deliverables.
Event
Incidents, deployments, hackathons, meetings, and other time-bound occurrences. Events have dates and participants.
Documentation
Runbooks, ADRs, guides, policies, and other reference materials. Documentation landmarks centralize important information.
External
Vendors, SaaS tools, partners, and third-party services. External landmarks help you track dependencies outside your organization.
Landmark Properties
Section titled “Landmark Properties”Every landmark has a set of properties that define it:
Required properties:
- Name: The display name of the landmark (e.g., “Billing API”, “PostgreSQL Primary”)
- Category: The type of landmark (service, resource, project, etc.)
Optional properties:
- Description: A brief summary of what the landmark represents
- Icon: A visual identifier from FontAwesome or a custom URL
- Owner: The team or person responsible for this landmark
- Tags: Labels for organization and filtering (e.g., “production”, “critical”, “deprecated”)
- Links: Quick-access URLs to documentation, dashboards, repositories, or other resources
- Documentation: Markdown files attached to the landmark for detailed information
- Pinned: Whether the landmark appears at the top of lists
- Featured: Whether the landmark is highlighted in special views
When to Create a Landmark
Section titled “When to Create a Landmark”Create a landmark when you have something that:
-
Multiple people need to know about: If information about a service, project, or resource is scattered across emails, chat messages, and people’s heads, centralize it in a landmark.
-
Has an owner: If someone is responsible for maintaining, updating, or answering questions about something, create a landmark and assign that owner.
-
Has dependencies: If other services or projects depend on this thing, create a landmark so you can track those relationships and understand impact.
-
Has documentation: If runbooks, guides, or reference materials exist for this thing, attach them to a landmark so people can find them.
-
Is referenced frequently: If people often ask “where is the documentation for X?” or “who owns Y?”, create a landmark to provide a single source of truth.
Examples of Good Landmarks
Section titled “Examples of Good Landmarks”- Billing API: A microservice that processes payments (service category)
- PostgreSQL Primary: The main database cluster (resource category)
- Q4 Migration Project: An initiative to move to a new platform (project category)
- Incident 2024-03-15: A production outage that occurred on a specific date (event category)
- Deployment Runbook: Step-by-step instructions for deploying services (documentation category)
- Stripe: Your payment processor (external category)
When Not to Create a Landmark
Section titled “When Not to Create a Landmark”Avoid creating landmarks for:
-
Individual tasks or to-do items: These are too granular and transient. Use your project management tool instead.
-
Temporary or ephemeral things: If something exists for less than a week and won’t be referenced again, it probably doesn’t need a landmark.
-
Personal notes: Landmarks are for shared organizational knowledge. Use a personal note-taking tool for individual work.
Landmarks in the User Interface
Section titled “Landmarks in the User Interface”Landmarks appear throughout Legend:
- Dashboard: Landmark cards display in the main grid alongside people and teams
- Search: Search for landmarks by name, description, tags, or documentation content
- Filters: Filter the dashboard to show only landmarks using the type filter
- Topology: Visualize landmark dependencies and relationships in the topology explorer
- Detail drawer: Click a landmark card to see full details, relationships, and documentation
Landmarks vs Other Entity Types
Section titled “Landmarks vs Other Entity Types”Legend has three entity types: landmarks, people, and teams. Understanding when to use each:
- Landmark: Something in your organization (service, project, resource, etc.)
- Person: An individual contributor with expertise and team affiliations
- Team: An organizational unit with hierarchical structure
Landmarks can be owned by people or teams. People can belong to teams. Teams can own landmarks. These relationships form the knowledge graph that makes Legend powerful.