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.
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.
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.
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:
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.
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.
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
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.
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.
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.
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.
Here are a couple of prompts for you to think about over the next month:
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.