Sharing your work on Discourse
If you’ve done something in your dbt project that you think others can learn from, Discourse is the best place to write about it.
Increasingly, we’re moving towards Discourse being the place that practitioners share their tips and tricks. While Stack Overflow is a great place to ask questions with objectively correct answers, Discourse is more suited to discussing ideas that don’t have one right answer.
Check out some of these existing articles that are well-suited to Discourse:
- How to create near real-time views with just dbt + SQL
- Using snapshot-based tests to detect regressions in historic data
- Using dbt and Snowflake shares
- Performing blue/green deploys of your dbt project
- Handling hard deletes when using snapshots
- How we structure our dbt projects
If you want to share your work on Discourse, here are some common patterns that make an article great. The article, “How to create near real-time views with just dbt + SQL” does almost all of these things perfectly — check it out as a reference!
Share the context of your problem #
It’s useful to know why you took on a particular challenge. This helps readers understand if the article is relevant to them.
Discuss alternative approaches to solving the problem #
There’s usually more than one way to peel a potato, and you may have tried some other things first before settling on the solution. What worked about those, what didn’t?
If there’s relevant open issues in dbt or other discussions that inspired your work, link them here! This might also fit better at the end of the article
Share your solution #
Now for the fun part — showing off your work.
First off, if there’s a concept you need to explain, make sure to do that. This might mean creating a diagram, or including some sample queries.
Then share your solution via code snippets and possibly an example! Consider:
- Generalizing the code to a familiar, but simpler, example — this can make it easier for someone to understand your work. Check out this example for EAV models — there’s example data + SQL to help readers along the way.
- Linking to a complete repo with code. We’ve been using this approach more and more, via the labs repo — each sub-directory includes code for demonstrating a solution. By sharing a sample repo, you often get all the benefit of open-source code, with very little maintenance burden (especially compared to maintaining a dbt package). If you go down this route, consider using a seed for mock data and include instructions in the README.
- Including a Loom video of you walking through the solution — these can be a great way to show multiple aspects at once.
Discuss trade offs #
Often, Discourse articles demonstrate advanced use-cases, which may introduce some complexity to your dbt project. Discussing these tradeoffs helps the reader understand whether the solution is right for them.
Discuss next steps #
Is the problem fully solved? Is there another solution that you haven’t yet tried? Let the community know what you’re thinking and what you’re blocked by. The comments section of Discourse is a great way to get feedback from community members.
Other tips: #
Leverage formatting #
You can write in Markdown on Discourse! Leverage code blocks and headings to help your reader along the way.
Be yourself #
The dbt community is a community of people, not companies, so we encourage you to write as yourself by adding your own voice.
Ask for feedback on a draft #
If this is your first time contributing some technical writing, feel free to share a draft for us to give feedback on. It’s a win-win situation: you’ll get to polish an important skill, and the community gets to benefit from your knowledge!