Presenting an idea to a busy decision-maker can be challenging. The key is to be clear and concise. In this issue, you'll explore the Minto Pyramid and how you can use it to pitch your next idea. You'll also explore a CLI tool for testing links in your content.

Scan Links with Lychee

If you're maintaining content, you'll find that part of that job is ensuring the things you link to are still intact. Lychee is a fast command-line tool for scanning links, and you can use it as a GitHub Action as well.

While it can scan live websites, it can also find links in Markdown documents and local HTML files, so you can integrate it into your development process.

To get it on your Mac, use Homebrew:

$ brew install lychee

You can also get binaries for your OS on the releases page.

To scan your local files, just pass it a file path. For example, to scan all the files in the local directory, run it like this:

$ lychee .

You can also restrict the scan so it only looks at local URLs and doesn't make network requests:

$ lychee --offline .

In addition to checking for links, Lychee can also scan for anchor links on a page. Supply the --include-fragments argument to enable this feature.

You can also tell Lychee to skip checking certain links. For example, you may have social media links in the footer of every page, so you might not always want to check them. Use the --exclude option to skip them:

lychee --exclude '(facebook|x|youtube|linkedin|instagram)\.com' .

If you happen to have a lot of links to GitHub on your site, you may get rate-limited and get a bunch of false-positive results, but you can get a GitHub Access Token and tell Lychee about it. You can use the --github-token argument, or set the GITHUB_TOKEN environment variable in your shell.

Lychee isn't a spider, so it can't follow links and crawl your site. You'll have to provide Lychee a list of URLs to scan. That's why it works well as a development tool. But if you do want to periodically scan all the pages on your live site, you can use your site's sitemap.xml file and parse out the URLs. Here's an example command that downloads the sitemap, extracts the location entries, and passes them all to Lychee:

$ curl https://yoursite.com/sitemap.xml \
  | sed -n 's:.*\([^<]*\).*:\1:p' \
  | xargs lychee --include-fragments

Since Lychee can scan URLs in plain-text documents, you can also provide your URLs that way.

Lychee is a handy tool to ensure your links to files and images stay up to date.

Things to Explore

• I've switched my terminal to Ghostty after many years with iTerm2. I like its file-based configuration system and the fact that it feels faster.
• Temporal released their Ruby SDK, and while it's still in alpha, I took it for a test drive and am very excited. Temporal lets you build resilient applications that recover from failure, and you can now take advantage of that in Ruby applications using an official SDK.
• Tailscale lets you create software-defined networks. Install the clients on your machines, log in on each device, and your devices can communicate securely no matter where they are in the world. The tsnet library lets you embed Tailscale into your Go application, which means you can build services that take advantage of Tailscale's features, including access control.

Concisely Pitch Your Next Big Idea

When you're pitching a great idea, it's natural to think you need to tell a detailed story. You'll start with the problem, talk about various things you could do, and then give "the big reveal," where you drop your recommendation. People who are natural storytellers are prone to this.

The problem with this approach is that decision-makers are juggling a long list of priorities. When you get their attention, every moment counts. Keeping the conversation focused on the core message shows respect for their time and ensures that your most crucial points remain front and center.

You can use the Minto Pyramid to create a clear, structured pitch that will help your idea stand out. Created by Barbara Minto, the Minto Pyramid Principle helps you organize your arguments so they are easier to follow and quick to understand.

Here's how it works. First, you present the main conclusion or recommendation. This signals the purpose behind your proposal. Next, group the supporting points that justify your conclusion. Each supporting point should address a specific reason why the idea is worth considering. Finally, include relevant details or data that reinforce these points. Moving from the big picture to the necessary specifics helps your audience track the logic. It also gives you a framework to organize your thoughts without getting too deep in the weeds.

Formulate the main idea

Start with a strong opening statement that conveys the recommendation or action you want.

This approach is also known as "BLUF," or "Bottom Line Up Front." You can quickly build out your recommendation with the Situation, Complication, Question, Answer (SCQA) framework:

• Situation (Context): Provide the backdrop and establish common ground. This is where you outline the "where and when," or any other relevant facts everyone agrees on.

• Complication (Problem): Introduce the core challenge or need that arises out of the situation. Explain why this issue matters right now.

• Question (Catalyst): Pose the question about how to overcome the problem or challenge.

• Answer (Main Idea) : Your recommendation or conclusion that resolves the complication.

This approach gives your recommendation a strong through-line that your key points will build upon.

When you're writing a proposal, the "Question" step can seem artificial or overly rhetorical if presented literally. Instead of asking a question, use a statement that highlights the gap between the current situation and the desired outcome rather than a question.

Now that you've gotten their attention, lay out your key points.

Create key supporting points

Your key points tie directly to the main idea and tackle a challenge or highlight a benefit. This is where you spell out the what and why behind your recommendation.

Start with the decision-maker's perspective. Identify the issues or goals your audience cares about most. This might include cutting costs, meeting deadlines, maintaining quality, or increasing team morale. Align each supporting point with these key concerns.

Highlight the Cause-and-Effect Relationship. Show how addressing one issue (such as improving accuracy) leads to direct benefits, like reduced errors or time saved. By illustrating the impact of each supporting point, you maintain a logical flow from problem to solution.

Ensure Each Point Adds Value. Avoid repeating the same argument in different words. Use each point to tackle a specific angle or benefit. Your goal is to create a natural progression of reasons that all converge on the conclusion.

Stay Brief and Focused. Your points should clarify, not distract your audience, so restrict your explanations to the most persuasive evidence, whether it's a quick anecdote, a small statistic, or a relatable comparison that resonates with your audience.

Once you've distilled a few key points into a couple sentences each, you can drill down a little deeper.

Reinforce your points

Back up each point with relevant facts, analysis, brief examples, or concise data. This combination of overview plus evidence gives your decision-maker both the logic behind your point and a snapshot of why it matters. This is where you'll show your work. You can explain things you tried, studies or surveys you did, and anything else that's relevant.

Generally, you'll keep this brief. You can provide additional resources for those who want to dig deeper or for you to reference if you get follow-up questions. Make these available as a full report or an appendix to your slide deck.

Here's a concrete example of the Minto Pyramid. Imagine you wanted to convince your leadership to adopt JIRA across the organization to manage projects. You've already done a trial and are ready to make a recommendation. Here's what your pitch might look like:

As you know, several projects are in flight, and we've been struggling to track the deliverables and provide visibility into our work across teams.

Without a unified process in place, confusion grows about who does what, leading to wasted time, last-minute scrambles, and costly delays. The risk of slipping timelines and overworked staff increases with every new project.

These ongoing issues undermine productivity and threaten to erode stakeholder confidence, highlighting the urgent need for a systematic solution.

I recommend we adopt JIRA as our centralized project management platform to streamline assignments, provide real-time updates, and clarify roles. This will keep tasks visible, prevent bottlenecks, and help all stakeholders stay aligned on priorities so we can deliver projects on time and within budget.

Key points

1. We'll have more predictable delivery. Centralizing all tasks and deadlines minimizes overlooked responsibilities. Stakeholders receive real-time notifications when due dates approach, which reduces last-minute scrambles.

   • Last month, we tested JIRA on a small pilot project involving two cross-functional teams. The real-time task notifications and unified board led to a 25% drop in late tasks. Everyone stayed updated on deadlines without digging through long email threads, and the built-in reminders ensured all stakeholders knew what needed attention each day.

2. We'll be able to allocate resources more effectively. A unified platform highlights our overall workload, allowing quick reassignments when someone is overloaded. Fewer bottlenecks mean faster handoffs and less stress on team members.

   • JIRA's dashboards highlighted exactly who was overloaded. During the pilot, we discovered one developer at 120% capacity while another stayed under 70%. By reallocating tasks, we balanced the workload before crunch time. This prevented last-minute scrambles and cut handoff delays on high-priority tasks by 15 percent.

3. We'll have reduced operational costs
   A single tool cuts down on redundant processes, like manual follow-ups or repetitive status meetings. Over a month, this saved time translates to tangible cost savings that can be reinvested in high-impact projects.

   • Better visibility and fewer mistakes saved an estimated $5,000 in that single pilot project. Automated status updates reduced the time spent on follow-up emails, and streamlined processes helped us avoid rework. Over a full quarter, those savings could multiply, allowing us to reinvest in additional team training or new features.

For more information, view the full report in Notion.

Notice how each supporting point reinforces the main idea and addresses a core concern. It focuses on facts that illustrate why this solution is worth pursuing and avoids unnecessary arguments that dilute the message. You then provide the rest of the deep dive so interested parties can learn more.

This principle works for any kind of pitch, whether it's within your team or something more substantial that's meant for the entire organization. Start with the conclusion, group the reasons that support it, and add only the data that proves those reasons. This method keeps your proposal clear and grounded in outcomes that matter to decision-makers.

Parting Thoughts

Here are a couple of prompts for you to think about over the next month:

• Take a project proposal you've seen or even one you've created. Did it use the Minto Pyramid? If not, how would it be different if it did? What would you change?
• Try running Lychee on your website and see how many broken links you find. Then see if you can build it into your writing process; have it check links on each document you create before you publish it.

Thanks for reading!

I'd love to talk with you about this newsletter on Mastodon, Twitter, or LinkedIn. Let's connect!

Please support this newsletter and my work by encouraging others to subscribe or by buying a friend a copy of Exercises for Programmers, Small, Sharp Software Tools, or any of my other books.