“All software is broken[, especially your own].”
This statement by my good friend Mattia (with the addendum by yours truly) stays with me regularly as a creative technologist. I’ve been building connected systems for close to two decades now, and it’s the most true statement about systems design I can think of.
No matter how methodical you are, things not only can break, but will, mostly in fun and exciting ways you weren’t accounting for when you designed the system.
So we get stuck. We get frustrated. And we seek more expertise or knowledge to remediate. Often in the context of asking, the emotional burden of the problem causes us to show up in ways that don’t support us getting the help we’re hoping to receive.
With that in mind, this guide is defined to prompt you to consider how to receive and give technical support effectively, from both a technical and emotional perspective. Does it apply to Notion? Absolutely. In fact, Notion is complex enough that we encounter issues and bugs regularly, and learning how to diagnose and get support for these issues can help us cope.
As I like to say, this shit doesn’t get easier, you just get better at it. Keep working at it and you can become a debugging master.
Asking for help: a systematic approach
Before reaching out for assistance, there’s significant value in developing a systematic approach to problem-solving. Essentially, you want to develop a few organized steps to understand your problem. Imagine you’re a detective—first you gather clues, then you test your theories, and finally you put the pieces together. A methodical approach not only helps you solve problems on your own more often, but when you do need help, you’ll be able to explain exactly what’s wrong and what you’ve already tried.
Okay, sometimes it looks like a cool detective noir, but mostly it looks more like our favorite Always Sunny meme…
I’m sometimes known not as problem-solver, but as a problem-finder, and my Notion often looks like the above image because I’m deep in finding mode. In fact, within the Notion community, I’ve become known as a bug-hunting champion. Last November alone, I spotted about fifty of them.
Through years of creating my own software (and yes, making plenty of mistakes along the way), I’ve developed what I like to think of as a mental toolkit for tackling problems. It’s like having a well-organized toolbox where every tool has its perfect place and purpose.
While software developers might nod along with these ideas, they’re actually useful for everyone. Whether you’re dealing with a glitchy computer, a stubborn chainsaw, or even a tricky situation with a friend, the same basic principles work surprisingly well. It’s like having a universal translator for solving life’s puzzles.
1. Document everything
What have you tried? Can you reliably “repro” (reproduce) the problem? Take the time to document your steps with screenshots, photos, and screen recordings. Often, the act of intentionally recreating what you think you did will reveal something you missed initially.
It takes time, but questions posed with clear repro steps get expert attention far more often than contextless “ah, it’s not working!” rants. I often try 2–3 or more times. I might try doing random stuff differently on each try. What changes? Capture every little difference no matter how trivial!
Over my career I’ve fixed bugs that took months to discover, yet the fix ended up being a simple change to a single line of code (or replacing an entire sub-system with something that works out-of-the-box).
Often the simplicity of the change has nothing to do with the difficulty of our adventure towards the solve. The process is the thing that matters as you get a little bit better at identifying problems and processes for identifying problems the more you practice this.
Everything (every thing) matters—document everything.
It might feel like it takes more time to do this, but setting the scene with more context initially will help prevent a lot of back and forth when trying to get your question answered.
2. Define the problem
Can you describe the issue fully in succinct language? Write exactly what you did and what’s happening. Nothing hinders getting help more than simply saying “it’s broken.” How is it broken? When is it broken? Be specific about the behavior you’re observing (see point 1) and what you believe causes the behavior.
Often in repros engineers expect these key pieces of information:
- What happened?
- What are the steps to reproduce what happened?
- What did you expect to have happened?
This gives us both the observed behavior and a clear understanding of what our expectations are. Often-times an engineer will come back and say “yes, that’s expected behavior”, and then you can have a fun conversation about why you think that something else should happen. But at least then you know the problem isn’t the way you used the tool, but the way the tool is designed. This may promote a feeling of relief. Then again, it might not!
3. Research thoroughly
Take result from step 2 and Google it. Use DuckDuckGo and other search engines as well. Try multiple search vectors, AI, StackOverflow, forums, Bluesky, et al.
You might think your problem is unique, but I can almost always find a resource when I’m asked questions (see also: “I have an idea for an app that no one else has thought of”).
4. Change contexts
Change the context in which you are working. Is it working in a different browser? What if you reset the app? incognito window? Different machine? Clear cookies and cache?
Have you followed debugging processes offered by the software yet? Are there any guides available that other users have created? For example, I made a guide to Debugging Notion early on in my practice that I refer to regularly. Creating your own debugging guides can be super helpful. Many software creators create README files in their code repositories that describe common issues with the software for other people to review and add to if necessary.
5. Isolate the issue
Reduce the complexity in showcasing the issue. Can you take the whole system apart and look at the problem modularly? Great for things like writing code/formulas; start with the simplest step in the formula and test each step as you go. When does it begin to fail? That could be notable; also fantastic for getting support! If you give me a simple data-light Notion template I can fix and send back to you, how great is that for both of us?
I often ask Notion Mastery students to recreate the setup that highlights the problem with just what’s necessary to test the problem they’re encountering. The more tightly bound to other complexity the problem is, the harder it’s going to be to identify and being able to play in the actual software with the problem makes providing help much easier than watching a video of the problem-haver working through the issue on their own in a non-interactive space.
6. Consider the domain
What kind of problem is it? Is this within the tech or business domain? Consider how much a person who is not in your field of expertise needs to understand in order to identify the underlying technical problem. Also part of isolating the problem, but could you pose the problem in a way that doesn’t involve the end-user having to understand your specific domain? Can you describe the problem in a context that a non-domain-expert might understand?
Many times I get questions where a person starts with a detailed explanation of their entire industry or field, only to end up with a question that’s much simpler and more universal. While I genuinely enjoy learning about different fields (sometimes this background helps us find unexpected solutions!), there’s real value in being able to explain your problem both ways—within your specific context and as a standalone issue.
Think of it like describing a car problem. You could say “I’m a delivery driver who needs my van to handle multiple stops in the city, and lately when I…” or you could simply say “My brakes are squeaking.” Being able to do both shows you truly understand your problem, and it lets us have a more flexible conversation where we can zoom in and out of the technical details as needed.
7. What workarounds are available?
How else might you solve the problem? We often call these “workarounds”. It might not be exactly what you want, but it works for now until you can figure out the larger problem. Also great for sharing with companies to highlight how annoying a UX issue or bug is!
Sometimes exploring a workaround can lead to a surprisingly helpful or even stronger solution to your problem that you hadn’t considered.
Still flummoxed?
It might be time to ask for help! At this point, you could create a document posing both the problem statement and the question. Consider the context here as well. For example, publishing a repro with steps, videos, demos of the issue in the platform you might have the problem with is a great way to progress through the issue.
I often use a Bug Repros database in Notion to isolate and share the bug so that I can share that with Notion’s support team or publicly share a link to see if anyone else is encountering a similar issue. This is also strategic in that I can update these docs as I discover new information about the repro. I can also return to these pages to confirm bugs are fixed!
In some cases I’ve been able to get a bug fixed in Notion by providing the engineering team clear steps to produce the bug and videos showing how to create the problem.
For example, I recently got an engineer to notice a long-running bug where “Hide when empty” doesn’t work in some properties. They couldn’t repro, so I created a simple setup and recorded a video for the key steps to making the bug appear. Being able to share that with the team lead to things getting fixed. But they couldn’t get there without seeing the exact steps because they didn’t have my context yet.
Often problems in software are caused by wacky things like small differences in timezone, so if the entire engineering team is in San Francisco, a user in Indonesia might find something really interesting happens when they use the software. How might your specific situation be highlighting the issue?
It’s often difficult for software teams to see the things that are relevant to their customers for various reasons such as:
- Limited investment in improvements (focused on new features).
- Internal teams often use private “dev” versions of the software not on production servers.
- Poor quality assurance systems.
- Larger teams can become very siloed, leading to some teams not understanding interrelated parts of the application.
All software is broken; yes, that is a given. Having these troubleshooting skills in your pocket can help you, your team, and your customers. I guarantee if you practice your documentation writing (and not just documented working systems, but dysfunctional ones, especially!) you will have less friction in both your digital workspaces and meatspaces.
Post-ask documentation
The bonus of documenting everything you know and discover: it’s highly valuable. Marie and I built Notion Mastery by doing exactly what I describe above and bundling it as a resource. I often think the meat of our program is actually the live office hours events where we—in real time—highlight how we do problem solving in Notion.
From the questions I ask to how I unpack a problem to how I write how I might solve it in a document so other students can replay and learn as well. The artifacts of troubleshooting are very valuable (you might be able to guess here as to why AI is so “good” right now).
“Personally, I like seeing the debugging process, it helps me learn more about how Notion formulas work and see how an expert troubleshoots it.”
— Olga Botvinnik
Being okay with uncertainty
If you’ve tried all these things and no one seems to be able to help you navigate the issue, you might be at the end of your rope. Not a great feeling, to be sure.
For example, often Notion API users are looking for a workaround for uploading files to Notion, but Notion does not offer any such feature at all, so there’s no workaround. It’s just something we have to live with or make the choice to host the files externally and use the API to link to them. Not ideal, but it is something.
Sometimes we have to accept that we can’t resolve our technical issue and there is no one to help. In cases like this, I try to really sit with the frustration. It’s okay to be frustrated. As a software creator, this is more or less expected. Nothing wrong with that. Often deep frustration turns to determination. How awesome would it be if no one can help you, but you decide that the problem is unacceptable so you do the work to build the help for yourself? What an opportunity.
Accept that progress isn’t clean. The cracks and flaws often reveal what truly matters to us.
When we obsess over finding the perfect technical solution, we can end up paralyzed, stuck in place while searching for an idealized answer that may never come. There’s power in sitting with discomfort—in acknowledging that something isn’t working while staying grounded in the knowledge that you’ll be okay despite the imperfection.
Giving help: the language of support
What about when we’re analyzing a question or a problem and we find enough motivation or interest to want to step in and help someone else?
The way we communicate when providing help can significantly impact its effectiveness. I wrote about this previously many years before AI took over as a key information gathering tool. With AI, we can use prompting to condition our language to be highly encouraging or brutally terse. We can “speak back“ to AI tools as curtly as we like.
It’s good to remember that people aren’t LLMs, and so considering the language we use is paramount.
Here are key considerations for offering assistance:
Choose your words carefully
It might sound trivial, but it’s good to avoid some key words that might make the question-asker feel insecure about asking a question. You can think of this as really believing there are “no stupid questions” and being mindful about reinforcing that in how we answer.
- “Simply”: This word implies that the solution is easy, but simplicity is relative to experience level. Only use “simply” to indicate actual brevity, not to describe the difficulty of implementation.
- “Obviously/Clearly”: These words assume shared knowledge or experience that may not exist. Don’t assume prior knowledge; instead, try to discern the experience level of the person asking for help.
- “Seriously?”: Avoid judgmental language that might belittle someone’s approach or understanding. Focus on providing solutions rather than criticizing methods.
Best practices for technical communication
Drawing from NASA’s “Writing Effective Requirements Specifications”:
- Avoid fuzzy words with relative meanings like “easy,” “normal,” “adequate,” or “effective”.
- Be precise with imperative usage.
- Consider context and audience carefully.
- Choose words that don’t leave room for multiple interpretations.
Remember that while these words have their place in casual conversation with colleagues you know well, they should be used more carefully in public forums where the audience’s experience level is unknown.
Receiving Help: The Emotional Landscape
There’s a cultural dimension to seeking help that needs addressing. Many people apologize for needing assistance, even in emergency situations. This reflects a broader culture of individualism where asking for help is often seen as shameful or burdensome.
When seeking help:
- Don’t apologize for needing assistance.
- Take the time to ask the “whole” question.
- Provide comprehensive context.
- Remember that most experts enjoy helping when given clear information.
The fear of being a burden often leads people to minimize their requests for help, but this can actually make it harder for experts to assist effectively. Detailed, well-documented questions often receive better responses than abbreviated ones.
Most devs enjoy debugging. But most devs dislike debugging communications. Don’t be afraid to ask for help, but ask the whole question.
- What did you expect to happen?
- What is happening?
- What did you try?
- What version of the software(s) are you using?
If the answer feels harsh, it can be helpful to remember that a person is really taking some time to try to help you. Sometimes I can feel defensive if someone answers a question I have in a terse tone, but…how can I extract what I need from it? Sometimes I have to sit with my own insecurity I may have felt for not being able to figure it out myself or not knowing the answer to begin with.
Building a better helping culture
We can work toward creating environments where:
- Wonder and curiosity are honored
- Questions are seen as opportunities for connection
- Help-seeking is normalized as a strength, not a weakness
- Documentation and sharing of solutions is valued
One of my favorite creators Jonny Miller will say “that’s beautiful, thank you for asking that” in response to a question; a sense of honouring wonder in others that feels inviting and connective in conversation. He’ll often take a moment to pause, breathe, and let the question settle in his body. This can help us provide support from a deeply embodied place, meaning we can receive difficult questions that might otherwise trigger us at times.
Remember that all software has imperfections (and now that I’m writing this, I can acknowledge that “broken” is quite emotionally charged—we can always improve), and developing strong troubleshooting skills benefits not just you but your entire community. The process of documenting both functional and dysfunctional systems creates valuable resources for others facing similar challenges.
By approaching help-seeking and help-giving with intention and care, we can build more effective and supportive technical communities.
Notion tips in your inbox