Lessons Learned

The Lessons Learned module provides a knowledge base for capturing, sharing, and discovering insights from PPM projects and programs. It supports full-text search, category and tag filtering, community ratings with usefulness scoring, view counting for popularity tracking, and a tag cloud for visual discovery.

Overview

Organizational learning is one of the most frequently cited yet least consistently practiced disciplines in project management. Teams encounter the same problems across projects because insights from previous experiences are trapped in individuals' memories or buried in project closure documents that nobody reads.

ProBeya's Lessons Learned module addresses this by providing a living, searchable knowledge base where project teams capture what worked, what did not, and what they would recommend for future projects. Community ratings surface the most useful lessons, and the tag cloud enables discovery by topic. Every lesson is linked to its source project or program for context.

Getting Started

1. Navigate to Portfolio > Lessons Learned in the sidebar.
2. Click New Lesson to capture an insight from a project experience.
3. Fill in the category, description, impact assessment, and recommendation.
4. Add tags to make the lesson discoverable by topic.
5. Link the lesson to a specific project or program for context.
6. Browse existing lessons using the search bar, category filter, or tag cloud.
7. Rate lessons you find useful to help surface the most valuable insights.

Key Concepts

Lesson Structure

Each lesson learned entry contains:

• Category: classifies the type of insight

  • Process: improvements to project management processes
  • Technical: technical solutions, architecture decisions, or tooling insights
  • Communication: stakeholder engagement, reporting, or team communication
  • Risk: risk identification, assessment, or response strategies
  • Resource: staffing, skill gaps, capacity planning, or vendor management
  • Quality: quality assurance, testing, or compliance approaches
  • Other: insights that do not fit standard categories

• Description: detailed narrative of what happened and what was learned

• Impact: assessment of the lesson's significance (how much did this matter?)

• Recommendation: actionable advice for future project teams

• Phase: the project lifecycle phase where the lesson originated (e.g., planning, execution, closing)

• Tags: free-form labels for topic-based discovery

• Author: automatically set to the authenticated user who creates the lesson

• Project and Program: optional links to the source project or program

Usefulness Rating

Any organization member can rate a lesson on a 1-5 scale. Ratings follow an upsert pattern: each user has exactly one rating per lesson, and re-rating overwrites the previous value. The lesson's usefulness score is the denormalized average of all ratings, recalculated after each rating change.

This scoring mechanism surfaces the most valuable lessons without requiring editorial curation. High-rated lessons appear first in search results when sorting by "highest rated."

View Count

Each time a lesson's detail page is viewed, the view count increments. This provides a simple popularity signal that complements the usefulness rating. High view count combined with high rating indicates a widely known and valued lesson. High view count with low rating may indicate a controversial or outdated entry that needs review.

Tag Cloud

The tag cloud aggregates all tags across the organization's lessons and displays them with frequency-weighted sizing. More frequently used tags appear larger, helping users identify the most common knowledge areas. Clicking a tag filters the search results to lessons with that tag.

How It Works

Creating Lessons

Lessons are created with a mandatory category, description, and recommendation. The author is automatically set to the authenticated user. Optional fields include project/program linkage, impact assessment, phase, and tags. The lesson is immediately visible to all organization members.

Editing Lessons

Only the original author can edit their own lessons. This prevents unauthorized modifications to shared organizational knowledge while still allowing the author to correct or refine their entries. The authorization check compares the requesting user's ID with the lesson's authorId.

Deleting Lessons

Deletion follows the same authorization model: only the original author can delete their lesson. All associated ratings are automatically cascade-deleted by the database FK constraint.

Searching Lessons

The search procedure provides full-text filtering with multiple dimensions:

• Free-text query: ILIKE search across both description and recommendation fields. This is case-insensitive partial matching -- searching for "budget" will find lessons mentioning "budget overrun," "Budget planning," or "BUDGET CONTROL."
• Category filter: exact match on the category enum
• Project filter: exact match to show lessons from a specific project
• Tag filter: JSONB containment query -- the lesson's tags must include ALL specified tags (AND logic)

Results support four sort orders:

• Newest: most recently created first (default)
• Oldest: oldest first for historical review
• Highest rated: best usefulness score first
• Most viewed: highest view count first

Pagination is supported with configurable limit and offset.

Rating Lessons

The rating procedure upserts a 1-5 rating for the current user on a specified lesson. After the upsert, it recalculates the lesson's usefulness score as the average of all ratings. This keeps the denormalized score accurate without requiring an expensive aggregation on every search query.

Top Lessons Discovery

The getTopLessons procedure returns the ten highest-rated lessons for quick discovery. This powers the "Top Lessons" panel on the lessons dashboard, providing immediate value to users who have not yet explored the knowledge base.

Tag Cloud Generation

The getTagCloud procedure uses PostgreSQL's jsonb_array_elements_text function to unnest the JSONB tags array from all lessons, then groups by tag value and counts occurrences. Results are sorted by frequency descending, with the most popular tags appearing first.

Configuration

Setting	Location	Description
Category	Lesson creation form	Classification of the insight type
Tags	Lesson creation form	Free-form labels for discovery
Project link	Lesson creation form	Optional link to the source project
Program link	Lesson creation form	Optional link to the source program
Phase	Lesson creation form	Project lifecycle phase of origin
Sort order	Search filter bar	Newest, oldest, highest rated, or most viewed
Tag filter	Tag cloud or search bar	Filter by one or more tags

Permissions

• View lessons: all organization members with PPM access
• Create lessons: all organization members with PPM access
• Edit lessons: lesson author only
• Delete lessons: lesson author only
• Rate lessons: all organization members with PPM access
• Search and browse: all organization members with PPM access

Tips & Best Practices

• Capture lessons during the project, not just at closure: The most valuable lessons are captured while the experience is fresh. Encourage teams to record lessons during retrospectives and phase transitions, not just during the closing phase.
• Write actionable recommendations: A lesson without a clear recommendation is just a story. Always include specific, actionable advice that future teams can follow.
• Use consistent tags: Agree on a core set of tags across the organization (e.g., "stakeholder-engagement," "vendor-management," "schedule-risk"). Consistent tagging improves discoverability.
• Rate generously: The rating system works best when many people participate. Encourage team members to rate every lesson they read. Even a 3-star rating provides signal.
• Link lessons to projects: Contextual linkage helps future teams understand the circumstances under which a lesson was learned. A lesson linked to a specific project is more credible than a generic observation.
• Review top lessons during project kickoffs: Before starting a new project, review the top-rated lessons in relevant categories. This is the simplest form of organizational learning.
• Periodically review low-rated lessons: Lessons with consistently low ratings may be outdated, poorly written, or inaccurate. Consider editing or archiving them.

Troubleshooting

Issue	Cause	Resolution
"Only the lesson author can edit this lesson" error	Non-author attempting to edit	Only the original author can modify a lesson. Contact the author for changes.
"Only the lesson author can delete this lesson" error	Non-author attempting to delete	Same as above -- only the author can delete.
Search returns no results	Query too specific or no matching lessons exist	Broaden the search query, remove filters, or check spelling.
Tag cloud is empty	No lessons have tags	Add tags to existing lessons or encourage tagging in new entries.
Usefulness score not updating after rating	Browser cache showing stale data	Refresh the page. Scores are recalculated immediately at the database level.
View count seems inflated	Every detail page visit increments the counter	This is by design. View count reflects total page loads, not unique viewers.

Related Features

• Projects -- Lessons are linked to specific PPM projects for context
• Programs -- Lessons can be linked to programs for program-level knowledge capture
• Governance Framework -- Lessons learned reports are part of the governance reporting suite
• Stage-Gate Reviews -- Gate reviews are natural checkpoints for capturing lessons
• Risk Management -- Risk-related lessons help improve future risk identification and response